1 of 1

Payment transactions

In this section, you will find all the technical specifications of the IDPay product REST APIs for managing payment transactions.

Before you begin

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.

Endpoints:

Transaction creation

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, BIN, and last4 digits are used.

Note: If the company is configured to reuse transactions with the same data, please refer to the "Transaction Reuse" section.

If the validations determine that biometric capture is not required, the response will have a different status, and a capture link will not be generated, as shown below:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

This scenario will occur if you use the Pre or Super Pre modules, for cases where you use IDPay in the Checkout, as specified in the Features section.

Reuse of Transactions

It is possible to configure the company to reuse transactions that have the same data, avoiding "replicated transaction" errors. The reuse will occur under the following conditions:

A transaction is being created with the same orderNumber, identity.key, identity.value, company, card.binDigits, card.lastDigits, and value of a previously created transaction.
The previous transaction has not yet exceeded the expiration time configured for the company.

If the transaction to be created and the previous transaction do not meet these conditions, a new transaction will be created. Otherwise, the following are the possible responses:

If the previous transaction is in a final status, such as approved or inconclusive:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

If the previous transaction is still in an initial status, such as waiting or shared:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsIn[...]dQssw5c"
}

In this last case, the transaction still in an initial status will have its expiration date recalculated, based on the date of this request.

Transaction status query

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

To optimize the performance of your application, you can also implement our Webhook to know when to check the transaction status. See more in the Webhook section.

Obtaining the set of evidence for the transaction

The evidence set can only be generated for approved transactions.

The link returned for the evidence set is valid for five minutes after it is obtained. Therefore, it is important that this link is not saved, but rather used to download the evidence set.

Resending the transaction notification

It is also possible to configure the resending of notifications through the portal, without the need to implement it via API. To understand the possibilities, speak with the person responsible for your project.

Transaction cancellation

For a transaction to be canceled, it must be in the initial status (waiting).

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

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Payment transactions

In this section, you will find all the technical specifications of the IDPay product REST APIs for managing payment transactions.

Before you begin

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.

Endpoints:

Transaction creation

Create Transaction

Endpoint to create a new transaction.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction

Header parameters

Authorization*string

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

Body

identity*object

User identification data.

key*string

Type of user identification key.

Example: "cpf"

value*string

User identification key value. Must be sent without dots or dashes.

Example: "USER_CPF"

orderNumber*string

Order number associated with the transaction. This data will be used as an index in the portal and can be used as a foreign key between your system and IDPay.

Example: "123456"

company*string

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

Example: "f44f02e5-320e-497b-b346-8cf19b3ee2a4"

redirectUrlstring

URL to which the user will be redirected after completing the transaction. Possible values are: An https URL to redirect web pages or a URL Schema for redirection in native mobile applications.

Example: "https://example.com/redirect"

card*object

Information about the card used in the transaction.

binDigits*string

First 6 or 8 digits of the card.

Example: "12345678"

lastDigits*string

Last 4 digits of the card.

Example: "7890"

expirationDatestring

Card expiration date.

Example: "12/24"

name*string

Cardholder's name. The name field must be sent correctly, avoiding encoding issues, incorrect or invalid values, which may cause problems with approval in the flow, as this data is used in the user experience and communication.

Example: "João da Silva"

value*number (float)

Total purchase value.

Example: 100.5

phonestring

Notification phone number. This parameter is optional, and if provided, a WhatsApp notification will be sent to the user.

Example: "5511998551010"

emailstring

Notification email. This parameter is optional, and if provided, an email notification will be sent to the user.

Example: "user@example.com"

captureBehaviorstring

Capture behavior defined for the transaction. Options available: 'biometric': The identity authentication model used is biometric only, for flows that always require biometric capture. 'silent': The identity authentication model is silent, validating only device metadata, for flows where no friction is desired (approval rate is lower). 'adaptive': A hybrid between the two above, using adaptive validation and biometrics. This flow has lower friction, security, and a better approval rate (default).

Example: "biometric"

additionalInfoobject

Additional information about the transaction. Currently, the following additional information can be sent: Seller: Information about the seller of that transaction. Seller identification (CPF or CNPJ) can be provided.

sellerobject

Seller information.

identityobject

key*string

Type of seller identification key.

Example: "cpf"

value*string

Seller identification key value.

Example: "12345678909"

Response

Transaction successfully created.

Body

idstring

ID of the created transaction.

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

statusstring

Current transaction status.

Example: "waiting"

linkstring

Link related to the transaction.

Example: "https://aces.so/test"

tokenstring

Signed token containing the necessary parameters to initialize Unico IDPay web SDK.

Example: "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"

Request

Response

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, BIN, and last4 digits are used.

Note: If the company is configured to reuse transactions with the same data, please refer to the "Transaction Reuse" section.

If the validations determine that biometric capture is not required, the response will have a different status, and a capture link will not be generated, as shown below:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "fast-inconclusive"
}

This scenario will occur if you use the Pre or Super Pre modules, for cases where you use IDPay in the Checkout, as specified in the Features section.

Reuse of Transactions

It is possible to configure the company to reuse transactions that have the same data, avoiding "replicated transaction" errors. The reuse will occur under the following conditions:

A transaction is being created with the same orderNumber, identity.key, identity.value, company, card.binDigits, card.lastDigits, and value of a previously created transaction.
The previous transaction has not yet exceeded the expiration time configured for the company.

If the transaction to be created and the previous transaction do not meet these conditions, a new transaction will be created. Otherwise, the following are the possible responses:

If the previous transaction is in a final status, such as approved or inconclusive:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

If the previous transaction is still in an initial status, such as waiting or shared:

{
    // previous transaction information
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "waiting",
    "link": "https://aces.so/teste",
    "token": "eyJhbGciOiJIUzI1NiIsIn[...]dQssw5c"
}

In this last case, the transaction still in an initial status will have its expiration date recalculated, based on the date of this request.

Transaction status query

Get Transaction Status

Endpoint to check the current status of a specific transaction.

GEThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}

Path parameters

transaction_id*string

Transaction ID to check the status.

Header parameters

Authorization*string

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

Response

Transaction status retrieved successfully.

Body

statusstring

Current status of the transaction.

Example: "processing"

Request

Response

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

To optimize the performance of your application, you can also implement our Webhook to know when to check the transaction status. See more in the Webhook section.

Obtaining the set of evidence for the transaction

The evidence set can only be generated for approved transactions.

Get Transaction Evidence Set

Endpoint to get the evidence set of a specific transaction.

GEThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/probative

Path parameters

transaction_id*string

ID of the transaction for which the evidence set will be retrieved.

Header parameters

Authorization*string

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

Response

Probative file link retrieved successfully.

Body

linkstring

URL of the probative file.

Example: "https://unico.io/probative.pdf"

Request

Response

The link returned for the evidence set is valid for five minutes after it is obtained. Therefore, it is important that this link is not saved, but rather used to download the evidence set.

Resending the transaction notification

Resend transaction notification

Endpoint to resend notifications via email and/or phone for a specific transaction.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify

Path parameters

transaction_id*string

Transaction ID for which the notification will be sent.

Header parameters

Authorization*string

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

Body

phone*string

Phone number to send the notification.

Example: "NOTIFICATION_PHONE"

email*string

Email address to send the notification.

Example: "NOTIFICATION_EMAIL"

Response

Notification sent successfully.

Body

idstring

Unique ID of the generated notification.

Example: "b50ee24c-71eb-4a5d-ade1-41c48b44c240"

linkstring

Generated link for the notification.

Example: "https://aces.so/example"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "phone": "NOTIFICATION_PHONE",
      "email": "NOTIFICATION_EMAIL"
    }),
});
const data = await response.json();

Response

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

Transaction cancellation

For a transaction to be canceled, it must be in the initial status (waiting).

Cancel transaction

Endpoint to cancel a specified credit transaction.

PUThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/cancel

Path parameters

transaction_id*string

Transaction ID to be canceled.

Header parameters

Authorization*string

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

Response

Transaction successfully canceled.

Body

statusstring

Updated transaction status.

Example: "canceled"

Request

Response

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

Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Resend transaction notification

Endpoint to resend notifications via email and/or phone for a specific transaction.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify

Path parameters

transaction_id*string

Transaction ID for which the notification will be sent.

Header parameters

Authorization*string

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

Body

phone*string

Phone number to send the notification.

Example: "NOTIFICATION_PHONE"

email*string

Email address to send the notification.

Example: "NOTIFICATION_EMAIL"

Response

Notification sent successfully.

Body

idstring

Unique ID of the generated notification.

Example: "b50ee24c-71eb-4a5d-ade1-41c48b44c240"

linkstring

Generated link for the notification.

Example: "https://aces.so/example"

Request

const response = await fetch('https://transactions.transactional.uat.unico.app/api/public/v1/credit/transactions/{transaction_id}/notify', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "phone": "NOTIFICATION_PHONE",
      "email": "NOTIFICATION_EMAIL"
    }),
});
const data = await response.json();

Response

{
  "id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
  "link": "https://aces.so/example"
}

Create Transaction

Endpoint to create a new transaction.

POSThttps://transactions.transactional.uat.unico.app/api/public/v1/credit/transaction

Header parameters

Authorization*string

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

Body

identity*object

User identification data.

key*string

Type of user identification key.

Example: "cpf"

value*string

User identification key value. Must be sent without dots or dashes.

Example: "USER_CPF"

orderNumber*string

Order number associated with the transaction. This data will be used as an index in the portal and can be used as a foreign key between your system and IDPay.

Example: "123456"

company*string

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

Example: "f44f02e5-320e-497b-b346-8cf19b3ee2a4"

redirectUrlstring

URL to which the user will be redirected after completing the transaction. Possible values are: An https URL to redirect web pages or a URL Schema for redirection in native mobile applications.

Example: "https://example.com/redirect"

card*object

Information about the card used in the transaction.

binDigits*string

First 6 or 8 digits of the card.

Example: "12345678"

lastDigits*string

Last 4 digits of the card.

Example: "7890"

expirationDatestring

Card expiration date.

Example: "12/24"

name*string

Example: "João da Silva"

value*number (float)

Total purchase value.

Example: 100.5

phonestring

Notification phone number. This parameter is optional, and if provided, a WhatsApp notification will be sent to the user.

Example: "5511998551010"

emailstring

Notification email. This parameter is optional, and if provided, an email notification will be sent to the user.

Example: "user@example.com"

captureBehaviorstring

Example: "biometric"

additionalInfoobject

sellerobject

Seller information.

identityobject

key*string

Type of seller identification key.

Example: "cpf"

value*string

Seller identification key value.

Example: "12345678909"

Response

Transaction successfully created.

Body

idstring

ID of the created transaction.

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

statusstring

Current transaction status.

Example: "waiting"

linkstring

Link related to the transaction.

Example: "https://aces.so/test"

tokenstring

Signed token containing the necessary parameters to initialize Unico IDPay web SDK.

Example: "eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"

Request

Response

Payment transactions

Before you begin

Transaction creation

Reuse of Transactions

Transaction status query

Obtaining the set of evidence for the transaction

Resending the transaction notification

Transaction cancellation

Still need help?​

Payment transactions

Before you begin

Transaction creation

Create Transaction

Reuse of Transactions

Transaction status query

Get Transaction Status

Obtaining the set of evidence for the transaction

Get Transaction Evidence Set

Resending the transaction notification

Resend transaction notification

Transaction cancellation

Cancel transaction

Still need help?​

Resend transaction notification

Get Transaction Status

Get Transaction Evidence Set

Cancel transaction

Create Transaction

Still need help?

Still need help?