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.
Transaction creation
To ensure better conversion, create the transaction only after completing any pre-authentication or validation that could finalize the operation before the IDPay experience.
Endpoint to create a new transaction.
Valid access token. The value must be sent in the format "Bearer {token}".
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.
123456ID of the company responsible for the transaction. This field is provided by Unico.
f44f02e5-320e-497b-b346-8cf19b3ee2a4URL 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/redirectTotal purchase value.
100.5Notification phone number. This parameter is optional, and if provided, a WhatsApp notification will be sent to the user.
5511998551010Notification email. This parameter is optional, and if provided, an email notification will be sent to the user.
[email protected]POST /api/public/v1/credit/transaction HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 405
{
"identity": {
"key": "cpf",
"value": "USER_CPF"
},
"orderNumber": "123456",
"company": "f44f02e5-320e-497b-b346-8cf19b3ee2a4",
"redirectUrl": "https://example.com/redirect",
"card": {
"binDigits": "12345678",
"lastDigits": "7890",
"expirationDate": "12/24",
"name": "João da Silva"
},
"value": 100.5,
"phone": "5511998551010",
"email": "[email protected]",
"additionalInfo": {
"seller": {
"identity": {
"key": "cpf",
"value": "12345678909"
}
}
}
}{
"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.
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.
Transaction status query
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}.
GET /api/public/v1/credit/transactions/{transaction_id} HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Accept: */*
{
"status": "processing"
}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.
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}.
GET /api/public/v1/credit/transactions/{transaction_id}/probative HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Accept: */*
{
"link": "https://unico.io/probative.pdf"
}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
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_PHONEEmail address to send the notification.
NOTIFICATION_EMAILPOST /api/public/v1/credit/transactions/{transaction_id}/notify HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 59
{
"phone": "NOTIFICATION_PHONE",
"email": "NOTIFICATION_EMAIL"
}{
"id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
"link": "https://aces.so/example"
}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.
Last updated
Was this helpful?