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
https://onboard.smartkeys.engdev.fsapps.io/api/portal/onboard/v1/token
cURL for Token generation
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
{
"access_token": "...iJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...",
"expires_in": 3600,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}
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.
'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
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
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
{
"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…
Check out how to create your Journey Execution page for your customer, with an extract from the operation:
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:
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:
{
"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",
"localInstrument": "DICT",
"cnpjInitiator": "1393589...",
"payment": {
"amount": "1.15",
"currency": "BRL"
},
"remittanceInformation": "Pagamento Pix",
"creditorAccount": {
"accountType": "CACC",
"ispb": "9289...",
"issuer": "0...",
"number": "101..."
},
"debtorAccount": {
"ispb": "12345678",
"issuer": "1774",
"number": "1234567890",
"accountType": "CACC"
}
},
"links": {
"self": "https://api.opb.celcoin.dev.fsapps.io/open-banking/payments/v2/pix/payments/9be63638-3ef9-..."
},
"meta": {
"requestDateTime": "2023-09-12T19:11:56Z"
}
}
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 journey-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.
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>' \
Response model:
{
"data": {
"paymentId": "c0cede1b-564a...",
"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"
},
"remittanceInformation": "Pagamento Pix",
"creditorAccount": {
"accountType": "CACC",
"ispb": "60701190",
"issuer": "1500",
"number": "00611833"
},
"debtorAccount": {
"ispb": "12345678",
"issuer": "1774",
"number": "1234567890",
"accountType": "CACC"
}
},
"links": {
"self": "https://api.opb.celcoin.dev.fsapps.io/open-banking/payments/v2/pix/payments/c0cede1b-564a-4..."
},
"meta": {
"requestDateTime": "2023-09-13..."
}
}
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 .
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)
Example of Request for Registration of a WebHook
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,
"user": "",
"password": ""
}'
Example of Request for Pet Payment API to check payment status by Payment ID
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...' \
Call response
{
"paymentId": "30ddc97c-90d0-4ba6-b681-...",
"status": "ACCEPTED"
}
The status parameter can receive the values: "ACCEPTED", "AWAITING_APPROVAL" and "REJECTED"
Example of Request for Pet Payment API to check payment status by Consent ID
curl --location 'https://api-smartkeys.celcoin.dev.fsapps.io/api/smart-keys/payment-consumer/v1/pix/consents/yfPdbpcWgHQo1VL5vrYzd0xIRuxEUJqPO5ufvEN2esA' --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \
Call response
{
"paymentId": "30ddc97c-90d0-4ba6-b681-...",
"status": "ACCEPTED"
}
The status parameter can receive the values: "ACCEPTED", "AWAITING_APPROVAL" and "REJECTED"