Loading...
In this section, you will find all the available endpoints for the Unico IDPay product.
Loading...
Loading...
Loading...
Loading...
Loading...
In this section, you will find an overview of the errors you may receive from the endpoints of the Unico IDPay product.
Unico IDPay uses conventional HTTP response codes to indicate the success or failure of an API request.
As a general rule:
Codes in the 2xx range indicate success with the request.
Codes in the 4xx range indicate incorrect or incomplete parameters (for example, a mandatory parameter was omitted, or an operation failed with third parties, etc.).
Codes in the 5xx range indicate an error on the Unico IDPay product servers.
Unico IDPay also generates an error message and an error code formatted in JSON:
In this topic, you will find the possible errors for the endpoints, separated by their HTTP response.
400
40001
error decoding json
The data sent does not match the service contract.
400
40002
error validating json
Some information is poorly formatted or missing.
400
40021
invalid phone
The provided phone number is invalid, it must follow the format: 55 DDD NUMBER. For example: 5543999999999.
400
40022
invalid email
The provided email is invalid.
400
40027
replicated transaction
The transaction sent already exists and cannot be created again.
400
40045
max value reached
When the transaction reaches a value higher than the allowed limit.
403
40301
not allowed
The user does not have permission to perform this action.
404
40404
company not found
The provided company does not exist.
429
40001
too many requests
Rate limit reached.
500
50001
internal error
Internal service failure.
400
40001
error decoding json
The data sent does not match the service contract.
400
40002
error validating json
Some information is poorly formatted or missing.
400
40004
transaction id is invalid
The transaction ID is invalid (format).
400
40301
not allowed
The user does not have permission to perform this action.
429
40401
transaction not found
The transaction was not found.
500
50001
internal error
Internal service failure.
400
40004
transaction id is invalid
The transaction ID is invalid (format).
400
40009
transaction status is invalid
The transaction status is invalid (not allowed for generating the proof set).
403
40301
not allowed
The user does not have permission to perform this action.
404
40401
transaction not found
The transaction was not found.
500
50001
internal error
Internal service failure.
400
40001
error decoding json
The data sent does not match the service contract.
400
40002
error validating json
Some information is incorrectly formatted or has not been filled out.
400
40004
transaction id is invalid
The transaction ID is invalid (format).
400
40009
transaction status is invalid
The transaction status does not allow notification resend (it is already completed).
400
40021
invalid phone
The phone number provided is invalid, it must follow the format: 55 DDD NUMBER. For example: 5543999999999.
400
40022
invalid email
The provided email is invalid.
403
40301
not allowed
The user does not have permission to perform this action.
404
40401
transaction not found
The transaction was not found.
429
40001
too many requests
Rate limit reached.
500
50001
internal error
Rate limit reached.
400
40004
transaction id is invalid
The transaction ID is invalid (format).
400
40009
transaction status is invalid
The transaction status does not allow cancellation.
403
40301
not allowed
The user does not have permission to perform this action.
404
40401
transaction not found
The transaction was not found.
500
50001
internal error
Internal service failure.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
In this section, you will find everything related to the Unico IDPay APIs.
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.
If the validations determine that biometric capture is not necessary, the response will have a different status, and no capture link will be generated, as shown below:
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.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
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.
Endpionts:
Production: https://transactions.transactional.unico.app/api/public/v1. We
To see all possible statuses, refer to the Enumerated section.
To optimize your application's performance, you can also implement our Webhook to know when to query the Chargeback status.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.
In this section, you will find all the technical specifications of the IDPay product REST APIs for managing payment transactions.
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:
UAT: ;
Production: .
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:
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.
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:
If the previous transaction is still in an initial status, such as waiting or shared:
In this last case, the transaction still in an initial status will have its expiration date recalculated, based on the date of this request.
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.
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.
For a transaction to be canceled, it must be in the initial status (waiting).
In this section, you will find all the enumerations related to the Unico IDPay product.
To see all possible statuses, refer to the section.
To optimize the performance of your application, you can also implement our to know when to check the transaction status. See more in the Webhook section.
To see all possible statuses, refer to the section.
Didn't find something or still need help? If you're already a client or partner, you can reach out through our .
Didn't find something or still need help? If you're already a client or partner, you can reach out through our .
waiting
Intermediate
Waiting for information to be submitted
processing
Intermediate
In processing
shared
Intermediate
You have shared the capture, and we are waiting for the information to be submitted.
approved
Final
Approved
inconclusive
Final
We were unable to perform a conclusive validation.
expired
Final
Transaction expired
skiped
Final
The person skipped the biometric capture in the flow.
unknown-share
Final
The person marked that they do not recognize that purchase.
fast-inconclusive
Final
We were unable to perform a conclusive validation (pre-approval).
absent-holder
Final
When the cardholder is not present to complete the capture.
canceled
Final
When a transaction was manually canceled.
waiting
Intermediate
Awaiting analysis
analyzing
Intermediate
In the process of analysis
approved
Final
Approved
refused
Final
Rejected
Endpoint to check the current status of a specific transaction.
Transaction ID to check the status.
Valid access token. The value must be sent in the format Bearer {token}.
Transaction status retrieved successfully.
Current status of the transaction.
"processing"
Endpoint to check the status of a specific chargeback for a transaction.
Transaction ID associated with the chargeback.
Chargeback ID to be retrieved.
A valid access token. The value must be sent in the format Bearer {token}.
Chargeback status retrieved successfully.
Chargeback ID.
"8263a268-5388-492a-bca2-28e1ff4a69f0"
Current status of the chargeback.
"waiting"
Endpoint to validate a credit card.
A valid access token. The value must be sent in the format Bearer {token}.
User identification details.
Type of user identification key.
"cpf"
Value of the user identification key.
"12345678909"
Order number associated with the transaction. It will be used as an index in the portal and as a foreign key between your system and Unico IDPay.
123456
Company ID responsible for the transaction. This field is provided by Unico.
"7873959b-f7b2-4b81-8b0e-4ce178e64daf"
URL to redirect the user after completing the transaction. Possible values include an HTTPS URL for web pages or a URL Schema for native mobile app redirection.
"https://example.com/redirect"
Card details used in the transaction.
First 6 or 8 digits of the card.
"12345678"
Last 4 digits of the card.
"7890"
Card expiration date.
"12/24"
Cardholder's name. Ensure the correct name is sent, as encoding issues, incorrect, or invalid values can cause transaction approval issues. This information is used in the user experience and communication.
"João da Silva"
Phone number for notifications (optional). If provided, it will be used for WhatsApp notifications.
"+5511999999999"
Email address for notifications (optional). If provided, it will be used for email notifications.
"user@example.com"
Transaction created successfully.
Created transaction ID.
"6ab1771e-dfab-4e47-8316-2452268e5481"
Current transaction status.
"waiting"
Link associated with the transaction.
"https://aces.so/test"
Signed token containing the necessary parameters to initialize Unico IDPay's web SDK.
"eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"
Endpoint to get the evidence set of a specific transaction.
ID of the transaction for which the evidence set will be retrieved.
Valid access token. The value must be sent in the format Bearer {token}.
Probative file link retrieved successfully.
URL of the probative file.
"https://unico.io/probative.pdf"
Endpoint to resend notifications via email and/or phone for a specific transaction.
Transaction ID for which the notification will be sent.
A valid access token. The value must be sent in the format Bearer {token}.
Phone number to send the notification.
"NOTIFICATION_PHONE"
Email address to send the notification.
"NOTIFICATION_EMAIL"
Notification sent successfully.
Unique ID of the generated notification.
"b50ee24c-71eb-4a5d-ade1-41c48b44c240"
Generated link for the notification.
"https://aces.so/example"
Endpoint to cancel a specified credit transaction.
Transaction ID to be canceled.
A valid access token. The value must be sent in the format Bearer {token}.
Transaction successfully canceled.
Updated transaction status.
"canceled"
Endpoint to request a chargeback review for a specified transaction.
Transaction ID to be submitted for chargeback.
A valid access token. The value must be sent in the format Bearer {token}.
Chargeback request date and time in ISO 8601 format.
"2023-01-05T03:00:00.000Z"
Requestor's information.
Identification key type for the requestor.
"cpf"
Identification key value for the requestor.
"USER_CPF"
Name of the requestor.
"USER_NAME"
Reason for the chargeback request.
"REQUEST_REASON"
General observations about the request.
"GENERAL_OBSERVATIONS"
Documents related to the chargeback. Up to 3 items are allowed, and each document must be Base64 encoded. Only PDF files are accepted.
File name or description.
"FILE_NAME"
Base64 encoded PDF file.
"JVBERi0xLjQKMSAwI=="
Chargeback request successful.
Generated chargeback ID.
"8263a268-5388-492a-bca2-28e1ff4a69f0"
Endpoint to create a new transaction.
Valid access token. The value must be sent in the format "Bearer {token}".
User identification data.
Type of user identification key.
"cpf"
User identification key value. Must be sent without dots or dashes.
"USER_CPF"
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.
"123456"
ID of the company responsible for the transaction. This field is provided by Unico.
"f44f02e5-320e-497b-b346-8cf19b3ee2a4"
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.
"https://example.com/redirect"
Information about the card used in the transaction.
First 6 or 8 digits of the card.
"12345678"
Last 4 digits of the card.
"7890"
Card expiration date.
"12/24"
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.
"João da Silva"
Total purchase value.
100.5
Notification phone number. This parameter is optional, and if provided, a WhatsApp notification will be sent to the user.
"5511998551010"
Notification email. This parameter is optional, and if provided, an email notification will be sent to the user.
"user@example.com"
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).
"biometric"
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.
Seller information.
Type of seller identification key.
"cpf"
Seller identification key value.
"12345678909"
Transaction successfully created.
ID of the created transaction.
"6ab1771e-dfab-4e47-8316-2452268e5481"
Current transaction status.
"waiting"
Link related to the transaction.
"https://aces.so/test"
Signed token containing the necessary parameters to initialize Unico IDPay web SDK.
"eyJhbGciOiJIUzI1NiIsInR5cC[...]Ok6yJV_adQssw5c"
Endpoint to check the current status of a specific transaction.
ID of the transaction to be queried.
"6ab1771e-dfab-4e47-8316-2452268e5481"
A valid access token. The value must be sent in the format Bearer {token}.
Query successfully executed.
Current status of the transaction.
"processing"