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. Learn more in Authentication.

Base URL

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

Create Transaction

POST /credit/transaction — creates a new transaction.

danger

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

danger

The orderNumber field must be filled with the unique order number of that purchase in the e-commerce system — using a distinct transactional ID is incorrect. Reusing it can cause low conversion (the order number helps the end user complete the flow) and API errors such as replicated transaction if the same order number, CPF, BIN, and last 4 digits are used.

Headers

Header	Value
Authorization	Bearer {token} — a valid access token.

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "order-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/checkout/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 199.90,
  "mainContacts": [
    { "key": "phone", "value": "5543999999999" }
  ]
}

Field	Type	Required	Description
identity	object	yes	User identification data.
identity.key	string	yes	Type of user identification key. cpf is recommended — higher conversion rate.
identity.value	string	yes	User identification key value, without dots or dashes.
orderNumber	string	yes	Order number associated with the transaction. Used as an index in the portal and as a foreign key between your system and Card Not Present Verification.
company	string	yes	ID of the company responsible for the transaction, provided by Unico.
redirectUrl	string	no	URL to redirect the user after completing the transaction (an HTTPS URL for web, or a URL scheme for native mobile apps).
card	object	yes	Information about the card used in the transaction.
card.binDigits	string	yes	First 8 digits of the card.
card.lastDigits	string	yes	Last 4 digits of the card.
card.expirationDate	string	no	Card expiration date.
card.name	string	yes	Cardholder's name. Send it correctly, avoiding encoding issues — this data is used in the user experience and communication.
value	number	yes	Total purchase value.
mainContacts	array	no	List of main contacts (emails and/or phones) used to notify the user, when Card Not Present Verification is responsible for notification.
fallbackContacts	array	no	List of fallback contacts, triggered if the main contacts' notification attempts fail.

200 OK

{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-07-22T15:30:00Z"
}

Field	Description
id	ID of the created transaction.
status	Current transaction status.
link	Link related to the transaction.
token	Signed token containing the parameters needed to initialize the Card Not Present Verification web SDK.
expiresAt	Transaction expiration date and time, ISO 8601 (UTC).

warning

If the validations determine that biometric capture is not required, the response has a different status and no capture link is generated:

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

This happens when using the Pre or Super Pre modules for Checkout, per Feature.

For error responses, see Errors — Transaction Creation.

Get Transaction Status

GET /credit/transactions/{transaction_id} — checks the current status of a specific transaction.

Headers

Header	Value
Authorization	Bearer {token} — a valid access token.

200 OK

{
  "status": "processing"
}

Field	Description
status	Current status of the transaction.

See Enumerated for all possible statuses. To optimize performance, implement the Webhook instead of polling this endpoint.

For error responses, see Errors — Get transaction status.

Get Transaction Evidence Set

GET /credit/transactions/{transaction_id}/probative — retrieves the evidence set of a specific transaction.

warning

The evidence set can only be generated for approved transactions.

danger

The link returned for the evidence set is valid for five minutes after it is obtained — do not save it, use it to download the evidence set immediately.

Headers

Header	Value
Authorization	Bearer {token} — a valid access token.

200 OK

{
  "link": "https://unico.io/probative.pdf"
}

Field	Description
link	URL of the probative file.

For error responses, see Errors — Recovery of the evidentiary set of the transaction.

Resend Transaction Notification

POST /credit/transactions/{transaction_id}/notify — resends notifications via email and/or phone for a specific transaction.

note

It is also possible to configure notification resending through the portal, without implementing it via API. Talk to your project's point of contact to understand the possibilities.

Headers

Header	Value
Authorization	Bearer {token} — a valid access token.

Body

{
  "phone": "NOTIFICATION_PHONE",
  "email": "NOTIFICATION_EMAIL"
}

Field	Type	Required	Description
phone	string	yes	Phone number to send the notification.
email	string	yes	Email address to send the notification.

200 OK

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

Field	Description
id	Unique ID of the generated notification.
link	Generated link for the notification.

For error responses, see Errors — Resending the transaction notification.