Credit card onboarding

In this section, you will find all the technical specifications of the IDPay product REST APIs for managing credit card onboarding transactions

Before you start

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

You can learn more about how to generate an access token here.

Base URL:

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1;

• Production: https://transactions.transactional.unico.app/api/public/v1.

Important

The "Credit Card Onboarding" can be performed by either requesting a selfie from the end user and completing the entire registration process, or by reusing the biometric captures from processes executed by other products of the Unico IDCloud platform:

• To reuse processes generated by other Unico IDCloud platform products, you must provide the reference process ID in the additionalInfo.processID field;

• The reference processes used must have been completed no more than 1 hour prior.

Validate credit card

post

Endpoint to validate a credit card.

Header parameters

AuthorizationstringRequired

Valid access token. Must be sent in the format "Bearer {token}".

Body

application/json

orderNumberstringRequired

Number associated with the onboarding. This value will be used as an index in the portal and can serve as a foreign key between your system and IDPay.

Example: 123456

companystringRequired

ID of the company responsible for the transaction. This field is provided by Unico.

Example: 7873959b-f7b2-4b81-8b0e-4ce178e64daf

redirectUrlstringOptional

URL to which the user will be redirected after completing the transaction. Possible values include: an HTTPS URL for web redirection or a Schema URL for redirection in native mobile apps.

Example: https://example.com/redirect

valuenumber · floatOptional

Maximum secured value.

Example: 10.5

Responses

200

Transaction created successfully.

application/json

idstringOptional

ID of the created transaction.

Example: 6ab1771e-dfab-4e47-8316-2452268e5481

statusstringOptional

Current transaction status.

Example: waiting

linkstringOptional

Link related to the transaction (only returned if additionalInfo.processID is not provided).

Example: https://aces.so/test

tokenstringOptional

Signed token containing the necessary parameters to initialize the Unico IDPay web SDK (only returned if additionalInfo.processID is not provided).

Example: eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c

400

Invalid request data.

application/json

403

Access forbidden (invalid token or insufficient permissions).

application/json

404

Resource not found.

application/json

500

Internal server error.

application/json

post

/walletid/transaction

HTTPcURLJavaScriptPython

POST /api/public/v1/walletid/transaction HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 347

{
  "identity": {
    "key": "cpf",
    "value": "12345678909"
  },
  "orderNumber": 123456,
  "company": "7873959b-f7b2-4b81-8b0e-4ce178e64daf",
  "redirectUrl": "https://example.com/redirect",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "7890",
    "expirationDate": "12/24",
    "name": "João da Silva"
  },
  "value": 10.5,
  "additionalInfo": {
    "processID": "6ab1771e-dfab-4e47-8316-2452268e5481"
  }
}

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "waiting",
  "link": "https://aces.so/test",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"
}

The orderNumber field must be filled with the UNIQUE order number of that purchase in the e-commerce system, and using a distinct transactional ID is incorrect.

It is important to pay attention to this field, as it may negatively impact the user experience in the final flow, causing issues with product usage.

Possible impacts include:

• Low Conversion:

  • The order number is used to help the end user complete the flow.

• API Errors:

  • You might encounter errors such as "replicated transaction" if the same order number, cpf, BIN, and last4 digits are used.

Check validation status

get

Endpoint to check the current status of a specific transaction.

Path parameters

transaction_idstringRequired

ID of the transaction to be queried.

Example: 6ab1771e-dfab-4e47-8316-2452268e5481

Header parameters

AuthorizationstringRequired

Valid access token. The value must be sent in the format Bearer {token}.

Responses

200

Query successfully executed.

application/json

statusstringOptional

Current status of the transaction.

Example: processing

hasIdentityChangedbooleanOptional

Whether an identity swap occurred in the transaction (optional).

Example: false

400

Invalid request data.

application/json

403

Access forbidden (invalid token or insufficient permissions).

application/json

404

Transaction not found.

application/json

500

Internal server error.

application/json

get

/walletid/transactions/{transaction_id}

HTTPcURLJavaScriptPython

GET /api/public/v1/walletid/transactions/{transaction_id} HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Accept: */*

{
  "status": "processing",
  "hasIdentityChanged": false
}

To view all possible statuses, refer to the Enumerated section.

To optimize your application's performance, you can also implement our Webhook to know when to check the transaction status.