Credit card onboarding

Before you start

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

Important

Credit Card Onboarding can be performed either by requesting a selfie from the end user and completing the full registration, or by reusing biometric captures from processes executed by other Unico IDCloud platform products:

• To reuse processes generated by other IDCloud products, provide the reference process ID in additionalInfo.processID;
• The reference process used must have been completed no more than 1 hour prior.

Validate credit card

POST /walletid/transaction — validates a credit card.

Headers

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

Body

{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "onboarding-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/wallet/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 5000.00
}

Field	Type	Required	Description
identity	object	yes	User identity information.
identity.key	string	yes	Type of user identifier key.
identity.value	string	yes	Value of the user identifier key.
orderNumber	string	yes	Number associated with the onboarding. 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 Schema URL for native mobile apps).
card	object	yes	Card information 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 — ensure it's correct to avoid encoding issues or approval problems.
value	number	no	Maximum secured value.
additionalInfo	object	no	Send this object with processID to reuse biometric captures from other Unico IDCloud platform products.
additionalInfo.processID	string	yes (if additionalInfo is sent)	Reference process ID from the IDCloud platform.

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, and reusing values can trigger replicated transaction errors.

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

Field	Description
id	ID of the created transaction.
status	Current transaction status.
link	Link related to the transaction. Only returned if additionalInfo.processID is not provided.
token	Signed token to initialize the Card Not Present Verification web SDK. Only returned if additionalInfo.processID is not provided.

Check validation status

GET /walletid/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",
  "hasIdentityChanged": false
}

Field	Description
status	Current status of the transaction.
hasIdentityChanged	Optional. Whether an identity swap occurred in the transaction.

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

For error responses, see Errors — Credit card onboarding.