Page Comparison

Collection Open Keys - Payment Initiation Journey

View file

name	Smart-Key Pagamento - Celcoin.postman_collection.json

POST Token

Info
To start a journey, it is necessary to generate a token in which client_id and client_secret must be indicated , according to the model below.

...

Panel

bgColor	#F4F5F7

https://onboard.smartkeys.engdev8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/token

...

Code Block

curl --location 'https://onboard.smartkeys.engdev8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/token' \
--header 'Content-Type: application/json' \
--data '{   
    "client_id":"****7ec5-2567-4***-ace9-***",
    "client_secret": "****8136-***a-42ce-***"
}'

...

Code Block

curl --location 'https://onboard.smartkeys.celcoin8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \
--data '{
    "cpf": "401*****809",
    "name": "Fernando",
    "amount": "100.00",
    "paymentview": "deposit-confirmation",
    "paymenttype": "DICT"
}'

Mandatory fields to fill in the request:

CPF - mandatory field
Transaction amount - required field
Paymentview - required field
Paymenttype - required field

Specificity for Paymentview and Paymenttype fields

Paymentview PIX Instantâneo - deposit-confirmation
Paymentview PIX Agendado - deposit-deposit-scheduling
Paymenttype via DICT - presents the data registered in the Application Panel, option Configure Journeys, field Receipt data
Paymenttype via MANU - it is necessary to pass the “creditor” and “creditorAccount” blocks, as shown in the sketch below.

...

Code Block

curl --location 'https://onboard.smartkeys.celcoin8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ey*****J*****IsInR5c****CIgOiAiSldU*IiA6ICJ****JUV96OE...' \
--data '{
    "cpf": "02981994166",
    "name": "Fernando",
    "amount": "0.15",
    "paymentview": "deposit-confirmation",
    "paymenttype": "MANU",
    "creditor": {
        "cpfCnpj": "167******005",
        "name": "HOMOLOGACAO PIX",
        "personType": "PESSOA_NATURAL"
    },
    "creditorAccount": {
        "accountType": "CACC",
        "ispb": "92894922",
        "issuer": "0001",
        "number": "10173722"
    }
}'

Info
call response

Optional: External ID
When generating the payment initiation, it is possible to add an external ID using the object bellow, it is required:

The field is included inside object “data” at the same level of brandID;
The field name is “externalid".

Code Block
"metadata":{ "externalId": "000111" },

Info

Response:

The field externalid will be presented as a new parameter in callback url registered in the application.

Optional: Description
It is a string with the description of the pix that will be sent to the owner, maximum characters 140:

The field is included inside object “data” at the same level of brandID;
The field name is “description".

Code Block
"description": "Pix Description"

Optional: Tags
When generating the payment initiation, it is possible to add an tags using the object bellow, it is required:

The array maximum size to be up to 5 itens
The field is included inside object “data” at the same level of brandID;
The name of the tags must not be longer than 36 characters (to maintain the limitation on the number of characters)
- limitar os tipos de caracteres para Alfanuméricos e caracteres não reservados:
- `a-z`
- `A-Z`
- `0-9`
- `-`, `_`, `.`, `~`

Code Block
"metadata": { "tags": { "tag": "123456", "tag2": "SomeTag_2", "tag3": "AdditionalInfo", "tag4": "project_id", "tag5": "finalTag" } }

Info

Response:

All fields in Tags will be shown in the callback.

Optional: Preferred Banks
It is an array up to 8 itens from the brand-id list.

The order of the array is the same order that appears in the whitelabel

Code Block
"preferredbanks": [ "b09ede32-83db-4019-8ca3-a9a6f9376d0b"]

Note

It is only in the WhiteLabel solution:

And this information is not shown in the callback.

Optional: Pre-selected banks
It is a string with one brand from the brand-id list.

In case there is a preselected bank, the user goes directly to the final page for payment confirmation (before the redirect).
*Important to notice: the user will still be able to change the bank due to regulatory reasons.

Code Block
"preselectedbank": "b09ede32-83db-4019-8ca3-a9a6f9376d0b"

Info
call response

Code Block
{ "url": "https://smartkeys-wl.celcoin.dev.fsapps.io/select-institution?id=yL79m4Kzc7DI0WfL-QKW_k_2b5..." }

Note
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.

How to start the digital journey, using the Data Sharing 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

...

Code Block

curl --location 'https://onboard.smartkeys.celcoin8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/reception' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer e****GciOiJ*******nR5cCIgOiAiSldUIiw*****A6ICJJUV96OE...' \
--data '{
    "cpf":"01*****8010",
    "cnpj": "",
    "name":"fernando"
}'

Mandatory fields to fill in the request:

CPF - mandatory field, in all contexts
CNPJ - required field for a data sharing context for legal entities

Info
call response

...

context for legal entities

Info
call response

Code Block
{ "url": "https://smartkeys-wl.celcoin.dev.fsapps.io/?id=BYYPeLTrbfLABZcSeSMsJPFUWWsWBKq0" }

Info
Response with externalid

Code Block
{ "url": "https://smartkeys-

...

ui.

...

engdev.fsapps.io/

...

callback?ticket=eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwMTQ4ZjkxZS01NjA1LTRlYzktYWY3My0wM2UzOGNiNmIwNGUifQ.eyJleHAiOjE2ODA2MjU0MjUsIm5iZiI6MCwiaWF0IjoxNjgwNjIxODI1LCJwZXJtaXNzaW9ucyI6W3sicnNpZCI6IjNlN2Q4NTMxLWQ4MjMtNDg1Ny04NjZiLTZmMTg2OTMyNWY4NiJ9XSwianRpIjoiZjQzYTgzZWYtMGE0MC00ZTgyLThiOWMtZjhiZGFiNjM2ZWZiLTE2ODA2MjE4NTAwODMiLCJhdWQiOiJodHRwczovL2tleWNsb2FrLmZ1bGwtZGV2LmZpbmFuc3lzdGVjaC5jb20uYnIvYXV0aC9yZWFsbXMvc21hcnQta2V5cyIsInN1YiI6ImM4OTJkYjViLTUyMDktNDBhOS1iNGQwLTdjMmM4MzViYWM0OCIsImF6cCI6ImNlbGNvaW4ifQ.nhW9PVOlHE2sgzy4iU2MeqOi_QDAjI0rAf2isytNmXw&state=lPOOqD1D-Fjndvnt63moETZVIiTqpFRf4EVOFtATXuE&externalId=000111"
}

Note
ATTENTION: if the call is made in a partial request, in the AJAX model, you must capture the POST return to redirect the client, via window.

Known bugs:

400 - Failed to validate mandatory fields;
401 - Invalid Authentication Token

Alternative journey to start Payment Initiation white label

When starting the journey through the white label, by default, the user is directed to the bank selection screen. As part of this process, it is necessary to send the customer's CPF by parameters in the call to generate the white label link, but in cases where the application that starts the process does not yet have the customer's CPF, there is the possibility of showing the CPF field on this bank selection screen, as well as showing a list of preferred banks on this screen. For these cases, you can use the call below.

...

Code Block

curl --location 'https://onboard.smartkeys.celcoin8429y94d.dev.fsapps.ioapp/api/portal/onboard/v1/payment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJh******iOiJSUzI**********iAiSldUIiwia2lkIi*****CJJUV96OE...' \
--data '{
    "amount": "100.00",
    "paymentview": "deposit-confirmation-simple",
    "paymenttype": "MANU",
    "preferredbanks": ["b0e14b00-9686-4764-bdac-5fe415b1dc1a", "c8f0bf49-4744-4933-8960-7add6e590841", "95dd24d2-902e-49e1-ad0d-e02d938447ba"],
    "creditor": {
        "cpfCnpj": "16*****005",
        "name": "HOMOLOGACAO PIX",
        "personType": "PESSOA_NATURAL"
    },
    "creditorAccount": {
        "accountType": "CACC",
        "ispb": "92894922",
        "issuer": "0001",
        "number": "10173722"
    }
}'

...

Optional: External ID
In the same method as seen above.

Code Block
{ "url": "https://smartkeys-wl.celcoin.dev.fsapps.io/select-institution?id=yL79m4Kzc7DI0WfL-QKW_k_2b5..." }

Callback Page (Return of the White Label Payment Initiation flow)

After executing the consent flow and payment approval, the user is directed to the callback page registered at the time of onboarding, this page can check the approved payment status and show a thank you/failure message.

How to check the approved payment status update

Changing the status of the initiated payment can be done in 2 ways, registering a Webhook in the application or consulting the status of this consent via API (Polling)

Info
Example Request for Registering a WebHook

Code Block

curl --location 'https://api-smartkeysopenkeys.celcoin8429y94d.dev.fsapps.ioapp/api/smartopen-keys-itp/api/interceptor' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbG******OiJSUzI1N****iIsIn*****R5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \
--data '{
    "endpoint": "",
    "isAuthenticated": true,
    "user": "",
    "password": ""
}'

...

Info
Example Request for Pet Get Payment API to check payment status by Payment ID

Code Block

curl --location 'https://api-smartkeysopenkeys.celcoin8429y94d.dev.fsapps.ioapp/api/smartopen-keys-itp/api/payment-consumer/v1/pix/payments/0d42f0c8-f5ff-493f-a350-19d5b8b76618'
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJUV96OE...' \

...

The status parameter can receive the values: "ACCEPTED", "AWAITING_APPROVAL" and "REJECTED"

Info
Example Request for Pet Get Payment API to check payment status by Consent ID

Code Block

curl --location 'https://api-smartkeysopenkeys.celcoin8429y94d.dev.fsapps.ioapp/api/smartopen-keys-itp/api/payment-consumer/v1/pix/consents/yfPdbpcWgHQo1VL5vrYzd0xIRuxEUJqPO5ufvEN2esA'
--header 'Authorization: Bearer eyJhbGci******NiIsInR5cC*****IgOiAiSldU******Iiwia2lkIiA6ICJJUV96OE...' \

...

Version	Old Version 3	New Version Current
Changes made by	Yann da Silva Neves	Fernando Magalhães
Saved on	Sept 12, 2023	Sept 10, 2024

Page Comparison

Versions Compared

Key

POST Token

How to start the digital journey, using the Data Sharing white label

Alternative journey to start Payment Initiation white label

Callback Page (Return of the White Label Payment Initiation flow)

How to check the approved payment status update