I hired the white label journey. How should I pass the parameters?
Info |
---|
Once an application is created, a Token is generated. Follow the steps below to start the journey in the right way. |
To access your Client ID and Client Secret, you must open the Settings option, within your Application Panel;
Just copy the parameters and copy them into the Token API to generate the necessary call.
...
How to start the digital journey, using the ITP white label
Once you managed to generate the Token, according to the step by step of the previous step, just make a POST that will return the white label journey link
Request for starting the Digital Journey - using DICT
Code Block | ||
---|---|---|
| ||
curl --location 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--data '{
"cpf": "40193135809",
"name": "Fernando",
"amount": "100.00",
"paymentview": "deposit-confirmation",
"paymenttype": "DICT"
}' |
Mandatory fields to fill in the request:
CPF - Required field
Valor da transação - Required field
Paymentview - Required field
Paymenttype - Required field
Specificity for Paymentview and Paymenttype fields
Paymentview Alternative Journey to User insert the CPF inside the Open Keys Whitelabel - deposit-confirmation-simple
Paymentview PIX Instantâneo - deposit-confirmation
Paymentview PIX Agendado - deposit-deposit-scheduling
Paymenttype by DICT -presents the data registered in the Application Panel, option Configure Journeys, field Receipt data
Paymenttype by MANU - it is necessary to pass the blocks “creditor” and “creditorAccount, as shown in the sketch below.
Example of Request with MANU
Code Block | ||
---|---|---|
| ||
curl --location 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--data '{
"cpf": "02981994166",
"name": "Fernando",
"amount": "0.15",
"paymentview": "deposit-confirmation",
"paymenttype": "MANU",
"creditor": {
"cpfCnpj": "16781564005",
"name": "HOMOLOGACAO PIX",
"personType": "PESSOA_NATURAL"
},
"creditorAccount": {
"accountType": "CACC",
"ispb": "92894922",
"issuer": "0001",
"number": "10173722"
}
}' |
Call Response
Code Block | ||
---|---|---|
| ||
{
"url": "https://smartkeys-wl.celcoin.dev.fsapps.io/select-institution?id=yL79m4Kzc7DI0WfL-QK..."
} |
Note: if the call is made in a partial request, in the AJAX model, you must capture the POST return to redirect the client, via a window.
After redirect to this page, the client executes the consent creation/approval flow and at the end he is redirected to the Redirect URL (Callback page) registered into admin portal.
...
The redirect URI page will receive the following query string parameters:
ticket=eyJhbGciO…
state=HVLeXYgP6…
journey-id=iUT7Rhfk8…
To confirm that the payment was processed successfully (and the payment status) you may check the payment status through the Webhook on Payment Initiation or using the Pooling API
For example, the state parameter brings the consent ID, so you may use the Get Pix by ConsentId API, like below:
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/payment-consumer/v1/pix/consents/HVLeXYgP6…' \
--header 'Authorization: Bearer <PUT_HERE_THE_ACCESS_TOKEN>' \ |
The response is something like below:
...
Finansystech's Smart Payments Initiation Journey has the flexibility to intelligently adapt to the needs and contexts of your business!
With it, your customer's experience will be shaped according to the parameters you have available, which allows us to serve all contexts in the market.
Instant PIX payment method
When guiding your customer to the moment of closing the purchase, it will be necessary to inform them between the PIX Via Open Finance payment methods , among the other conventional options in your sales channel. The format in which the journey will be called is up to the strategy that your company defines, and you can use, for example, a QR Code or a link to activate the journey, via a button.
How to start the journey
In order for a company contracting the Open Keys solution to be able to call the Payment Initiation Journey, it is necessary to generate a token in which the client_id and client_secret of the operation must be indicated, indicated in the application panel, settings menu.
...
Token generation URL
Panel | ||
---|---|---|
| ||
|
cURL for Token generation
Code Block |
---|
curl --location 'https://onboard.smartkeys.engdev.fsapps.io/api/portal/onboard/v1/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id":"...-2567-....-ace9-...",
"client_secret": "...8136-....-42ce-..."
}' |
Response
Code Block |
---|
{
"access_token": "...iJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
} |
Note |
---|
The token returned in the “access_token” field has a default validity of 1 hour and must be used to make subsequent calls. It must be included in the Authentication parameter of the request header, preceded by the word “Bearer”, as shown in the example below. |
Code Block |
---|
'Authorization': 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' |
POST Payment Initiantion
With the token generated, it is necessary to pass it in the authorization of the /consents call , to obtain the user's consent and information.
This is the moment in which you can provide as much information as necessary to open consent, as a way of optimizing your customer's experience.
Fields present in the request and UX customization
CPF - If passed in the parameter, the journey presents the field filled in for your customer.
Transaction value - If passed in the parameter, the journey presents the field filled in for your customer.
Paymentview Instant PIX ( deposit-confirmation ) - The day of the transaction must be passed as the date and the code will recognize that it is an Instant PIX
Paymentview PIX Scheduled ( deposit-deposit-scheduling ) - With the parameter open, the code will recognize that this is an operation that will allow the customer to choose whether they want to pay immediately or schedule payment for a future date (within a maximum period of 12 months)
Specificity for the Paymentview and Paymenttype fields
Paymenttype via DICT - presents the data registered in the Application Panel, Configure Journeys option, Receipt data field
Paymenttype via MANU - it is necessary to pass the “creditor” and “creditorAccount blocks, as per the example in the sketch below.
You can use more than one account to receive payments. To always use the account registered in the application created with Finansystech, simply make the call using the DICT parameter in the Paymenttype field . If you choose to use any other account in your operation, simply pass the MANU parameter in the Paymenttype field with the desired account information such as Creditor and CreditorAccount fields. Check out the examples below.
Jornada Digital startup Request format - using DICT
Code Block |
---|
curl --location 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \
--data '{
"cpf": "**93135***",
"name": "Fernando",
"amount": "100.00",
"paymentview": "deposit-confirmation",
"paymenttype": "DICT"
}' |
Example of Request with MANU
Code Block |
---|
curl --location 'https://onboard.smartkeys.celcoin.dev.fsapps.io/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \
--data '{
"cpf": "***81994***",
"name": "Fernando",
"amount": "0.15",
"paymentview": "deposit-confirmation",
"paymenttype": "MANU",
"creditor": {
"cpfCnpj": "***81564***",
"name": "HOMOLOGACAO PIX",
"personType": "PESSOA_NATURAL"
},
"creditorAccount": {
"accountType": "CACC",
"ispb": "9289****",
"issuer": "00**",
"number": "***73*2"
}
}' |
Call response
Code Block |
---|
{
"url": "https://smartkeys-wl.celcoin.dev.fsapps.io/select-institution?id=yL79m4Kzc7DI0WfL-QKW_k_2b5..."
} |
...
Smart payments initiation journey slim flow
In the most optimized scenario of the Smart journey, when we receive the parameters indicating the transaction value , the payer's CPF/CNPJ and the indication of payment as Instant PIX , the customer will only need:
Inform which institution you wish to make the payment with;
Confirm the operation
Automatic redirection to the account holding institution
...
...
Authentication and payment confirmation steps
After automatic redirection to the environment of the institution holding the account, the customer will go through the authentication and confirmation steps of the operation , following the standards established by the chosen Financial Institution.
...
Journey completion stage
After this confirmation, the operation will be processed by Celcoin and the customer will be directed to your company's environment, where it is essential to present the journey completion screen with the transaction statement with the information provided by Callback.
...
The redirect URI page will receive the following query string parameters:
ticket=eyJhbGciO…
state=HVLeXYgP6…
Info |
---|
Check out how to create your Journey Execution page for your customer, with an extract from the operation: |
Implementando página de Callback (URL de redirecionamento)
Track payment status
To confirm whether the payment was processed successfully (and the status of the payment), you can track via Webhook in Payment Initiation or using the Pooling API .
For example, the state parameter brings the consent ID , so you can use the Get Pix by ConsentId API , as below:
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/payment-consumer/v1/pix/consents/HVLeXYgP6…' \
--header 'Authorization: Bearer <PUT_HERE_THE_ACCESS_TOKEN>' \ |
The answer is something like below:
Code Block |
---|
{ "data": { "paymentId": "9be63638-3ef9-4427...", "endToEndId": "E139358932023091...", "consentId": "urn:celcoin:1e308e7f-b705-...", "creationDateTime": "2023-09-12T19:11:38Z", "statusUpdateDateTime": "2023-09-12T19:11:42Z", "proxy": "55155...", "status": "ACSC", "paymentIdlocalInstrument": "9be63638-3ef9-4427...DICT", "endToEndIdcnpjInitiator": "E1393589320230911393589...", "consentIdpayment": "urn:celcoin:1e308e7f-b705-...", { "creationDateTimeamount": "2023-09-12T19:11:38Z1.15", "statusUpdateDateTimecurrency": "2023-09-12T19:11:42Z"BRL" }, "proxyremittanceInformation": "55155...Pagamento Pix", "statuscreditorAccount": "ACSC", { "localInstrumentaccountType": "DICTCACC", "cnpjInitiatorispb": "13935899289...", "paymentissuer": {"0...", "amountnumber": "1101...15", }, "currency": "BRL" "debtorAccount": { }, "remittanceInformationispb": "Pagamento Pix12345678", "creditorAccountissuer": {"1774", "accountTypenumber": "CACC1234567890", "ispbaccountType": "9289...",CACC" } }, "issuerlinks": "0...", { "numberself": "101https://api.opb.celcoin.dev.fsapps.io/open-banking/payments/v2/pix/payments/9be63638-3ef9-..." }, }, "debtorAccountmeta": { "requestDateTime": "2023-09-12T19:11:56Z" "ispb": "12345678", "issuer": "1774", "number": "1234567890", "accountType": "CACC" } }, "links": { "self": "https://api.opb.} } |
The journey ID
The journey ID is the unique identifier of the whitelabel flow, which links the beginning of the journey with the consent and payment created, as at the beginning of this flow the consent does not yet exist. It's the code yL79m4Kzc7DI0WfL-QK...
from our example above (payment creation response response).
For the WhiteLabel journey, the callback page receives an additional parameter which is travel-id , which can be used to identify whether the journey was initiated by the WhiteLabel flows or ITP API.
Once you receive this Journey ID, it can also be used in the following voting API to retrieve payment information as below.
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/openapi/smart-bankingkeys/paymentspayment-consumer/v2v1/pix/payments/journey/9be63638yL79m4Kzc7DI0WfL-3ef9-QK..."' \ --header 'Authorization: },Bearer <PUT_HERE_THE_ACCESS_TOKEN>' \ |
Response model:
Code Block |
---|
{ "metadata": { "requestDateTimepaymentId": "2023-09-12T19:11:56Z"c0cede1b-564a...", } } |
The Journey ID
The journey ID is the unique identifier for the whitelabel flow, that links the beginning of the journey with the consent and payment createds, since at the beginning of this flow the consent still does not exist. It is the code yL79m4Kzc7DI0WfL-QK...
from our example above (response from payment creation response).
For the WhiteLabel journey, the callback page receives an additional parameter that is the journey-id, which may be used to identify if the journey was initiated by the WhiteLabel or the ITP API flows.
After receiving this journey-id, it also may be used into the following polling API to retrieve the payment information, like below.
Code Block | ||
---|---|---|
| ||
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/payment-consumer/v1/pix/payments/journey/yL79m4Kzc7DI0WfL-QK...' \
--header 'Authorization: Bearer <PUT_HERE_THE_ACCESS_TOKEN>' \ |
And the response is like:
Code Block | ||
---|---|---|
| ||
{ "data": {"endToEndId": "E139358932023...", "consentId": "urn:celcoin:2331b021...", "creationDateTime": "2023-09-13T18:43:51Z", "statusUpdateDateTime": "2023-09-13T18:44:08Z", "proxy": "frndm...@gmail.com", "status": "ACSC", "localInstrument": "DICT", "cnpjInitiator": "1393589...", "payment": { "amount": "100.00", "currency": "BRL" }, "paymentIdremittanceInformation": "c0cede1b-564a...Pagamento Pix", "creditorAccount": { "endToEndId "accountType": "E139358932023...",CACC", "consentIdispb": "urn:celcoin:2331b021...60701190", "creationDateTimeissuer": "2023-09-13T18:43:51Z1500", "statusUpdateDateTimenumber": "2023-09-13T18:44:08Z", 00611833" "proxy": "frndm...@gmail.com" }, "statusdebtorAccount": "ACSC",{ "localInstrumentispb": "DICT12345678", "cnpjInitiatorissuer": "1393589...1774", "paymentnumber": {"1234567890", "amountaccountType": "100.00",CACC" } }, "currencylinks": { "BRL" },"self": "https://api.opb.celcoin.dev.fsapps.io/open-banking/payments/v2/pix/payments/c0cede1b-564a-4..." }, "remittanceInformationmeta": "Pagamento{ Pix", "creditorAccountrequestDateTime": {"2023-09-13..." "accountType": "CACC", "ispb": "60701190", "issuer": "1500", "number": "00611833" }, "debtorAccount": { "ispb": "12345678} } |
...
Tip |
---|
Consultation and registration of the operation |
After receiving a token return within the “ticket” tag, you must insert it in the next PIX receipt query call. To do this, you can use the Consent ID , the Journey ID or the Payment ID .
Tip |
---|
How to check approved payment status update |
Changing the status of the initiated payment can be done in 2 ways, by registering a Webhook in the application or by checking the status of this consent via API (Polling)
Info |
---|
Example of Request for Registration of a WebHook |
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/interceptor' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \ --data '{ "endpoint": "", "isAuthenticated": true, "issueruser": "1774", "numberpassword": "1234567890", "accountType": "CACC" } }, "links": { "self": "https://api.opb. }' |
Info |
---|
Example of Request for Pet Payment API to check payment status by Payment ID |
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/payment-consumer/v1/pix/payments/0d42f0c8-f5ff-493f-a350-19d5b8b76618'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \ |
Info |
---|
Call response |
Code Block |
---|
{
"paymentId": "30ddc97c-90d0-4ba6-b681-...",
"status": "ACCEPTED"
} |
The status parameter can receive the values: "ACCEPTED", "AWAITING_APPROVAL" and "REJECTED"
Info |
---|
Example of Request for Pet Payment API to check payment status by Consent ID |
Code Block |
---|
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/opensmart-bankingkeys/paymentspayment-consumer/v2v1/pix/paymentsconsents/c0cede1byfPdbpcWgHQo1VL5vrYzd0xIRuxEUJqPO5ufvEN2esA' -564a-4-header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE..." }, "meta": { ' \ |
Info |
---|
Call response |
Code Block |
---|
{ "requestDateTimepaymentId": "2023-09-1330ddc97c-90d0-4ba6-b681-...", } } "status": "ACCEPTED" } |
The status parameter can receive the values: "ACCEPTED", "AWAITING_APPROVAL" and "REJECTED"