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.

Base URL:

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

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

Create Transaction

post

Endpoint to create a new transaction.

Header parameters

AuthorizationstringRequired

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

Body

application/json

orderNumberstringRequired

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

companystringRequired

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

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

redirectUrlstringOptional

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

valuenumber · floatRequired

Total purchase value.

Example: 100.5

Responses

200

Transaction successfully created.

application/json

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

/credit/transaction

HTTPcURLJavaScriptPython

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

{
  "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,
  "mainContacts": [
    {
      "key": "phone",
      "value": "5521999999991"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ],
  "fallbackContacts": [
    {
      "key": "phone",
      "value": "5521988888882"
    },
    {
      "key": "email",
      "value": "[email protected]"
    }
  ]
}

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

To ensure better conversion, create the transaction only after completing any pre-authentication or validation that could finalize the operation before the IDPay experience.

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.

Get Transaction Status

get

Endpoint to check the current status of a specific transaction.

Path parameters

transaction_idstringRequired

Transaction ID to check the status.

Header parameters

AuthorizationstringRequired

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

Responses

200

Transaction status retrieved successfully.

application/json

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

/credit/transactions/{transaction_id}

HTTPcURLJavaScriptPython

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

{
  "status": "processing"
}

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.

Get Transaction Evidence Set

get

Endpoint to get the evidence set of a specific transaction.

Path parameters

transaction_idstringRequired

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

Header parameters

AuthorizationstringRequired

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

Responses

200

Probative file link retrieved successfully.

application/json

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

/credit/transactions/{transaction_id}/probative

HTTPcURLJavaScriptPython

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

Resend transaction notification

post

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

Path parameters

transaction_idstringRequired

Transaction ID for which the notification will be sent.

Header parameters

AuthorizationstringRequired

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

Body

application/json

phonestringRequired

Phone number to send the notification.

Example: NOTIFICATION_PHONE

emailstringRequired

Email address to send the notification.

Example: NOTIFICATION_EMAIL

Responses

200

Notification sent successfully.

application/json

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

post

/credit/transactions/{transaction_id}/notify

HTTPcURLJavaScriptPython

POST /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"
}

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.