Transacciones de pago
Antes de empezar
Tus solicitudes a la API se autentican mediante un token de acceso. Cualquier solicitud que no incluya un token de acceso válido devolverá un error. Obtén más información en Autenticación.
- UAT:
https://transactions.transactional.uat.unico.app/api/public/v1 - Producción:
https://transactions.transactional.unico.app/api/public/v1
Crear transacción
POST /credit/transaction — crea una nueva transacción.
Para garantizar una mejor conversión, crea la transacción solo después de completar cualquier preautenticación o validación que pudiera finalizar la operación antes de la experiencia de Verificación de Tarjeta No Presente.
El campo orderNumber debe completarse con el número de pedido único de esa compra en el sistema de e-commerce — usar un ID transaccional distinto es incorrecto. Reutilizarlo puede causar baja conversión (el número de pedido ayuda al usuario final a completar el flujo) y errores de la API como replicated transaction si se usan el mismo número de pedido, CPF, BIN y últimos 4 dígitos.
| Encabezado | Valor |
|---|---|
Authorization | Bearer {token} — un token de acceso válido. |
{
"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" }
]
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
identity | object | sí | Datos de identificación del usuario. |
identity.key | string | sí | Tipo de clave de identificación del usuario. Se recomienda cpf — mayor tasa de conversión. |
identity.value | string | sí | Valor de la clave de identificación del usuario, sin puntos ni guiones. |
orderNumber | string | sí | Número de pedido asociado con la transacción. Se usa como índice en el portal y como clave foránea entre tu sistema y Verificación de Tarjeta No Presente. |
company | string | sí | ID de la empresa responsable de la transacción, proporcionado por Unico. |
redirectUrl | string | no | URL para redirigir al usuario después de completar la transacción (una URL HTTPS para web, o un esquema de URL para apps móviles nativas). |
card | object | sí | Información sobre la tarjeta usada en la transacción. |
card.binDigits | string | sí | Primeros 8 dígitos de la tarjeta. |
card.lastDigits | string | sí | Últimos 4 dígitos de la tarjeta. |
card.expirationDate | string | no | Fecha de vencimiento de la tarjeta. |
card.name | string | sí | Nombre del titular de la tarjeta. Envíalo correctamente, evitando problemas de codificación — este dato se usa en la experiencia de usuario y en la comunicación. |
value | number | sí | Valor total de la compra. |
mainContacts | array | no | Lista de contactos principales (correos electrónicos y/o teléfonos) usados para notificar al usuario, cuando Verificación de Tarjeta No Presente es responsable de la notificación. |
fallbackContacts | array | no | Lista de contactos de respaldo, activados si los intentos de notificación de los contactos principales fallan. |
{
"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"
}
| Campo | Descripción |
|---|---|
id | ID de la transacción creada. |
status | Estado actual de la transacción. |
link | Enlace relacionado con la transacción. |
token | Token firmado que contiene los parámetros necesarios para inicializar el SDK web de Verificación de Tarjeta No Presente. |
expiresAt | Fecha y hora de expiración de la transacción, ISO 8601 (UTC). |
Si las validaciones determinan que no se requiere captura biométrica, la respuesta tiene un estado diferente y no se genera un enlace de captura:
{
"id": "6ab1771e-dfab-4e47-8316-2452268e5481",
"status": "fast-inconclusive"
}
Esto ocurre cuando se usan los módulos Pre o Super Pre para Checkout, según Feature.
Para respuestas de error, consulta Errores — Creación de transacción.
Obtener estado de la transacción
GET /credit/transactions/{transaction_id} — verifica el estado actual de una transacción específica.
| Encabezado | Valor |
|---|---|
Authorization | Bearer {token} — un token de acceso válido. |
{
"status": "processing"
}
| Campo | Descripción |
|---|---|
status | Estado actual de la transacción. |
Consulta Enumerados para ver todos los estados posibles. Para optimizar el rendimiento, implementa el Webhook en lugar de hacer polling a este endpoint.
Para respuestas de error, consulta Errores — Obtener el estado de la transacción.
Obtener conjunto probatorio de la transacción
GET /credit/transactions/{transaction_id}/probative — recupera el conjunto probatorio de una transacción específica.
El conjunto probatorio solo se puede generar para transacciones aprobadas.
El enlace devuelto para el conjunto probatorio es válido durante cinco minutos después de obtenerlo — no lo guardes, úsalo para descargar el conjunto probatorio inmediatamente.
| Encabezado | Valor |
|---|---|
Authorization | Bearer {token} — un token de acceso válido. |
{
"link": "https://unico.io/probative.pdf"
}
| Campo | Descripción |
|---|---|
link | URL del archivo probatorio. |
Para respuestas de error, consulta Errores — Recuperación del conjunto probatorio de la transacción.
Reenviar notificación de la transacción
POST /credit/transactions/{transaction_id}/notify — reenvía notificaciones por correo electrónico y/o teléfono para una transacción específica.
También es posible configurar el reenvío de notificaciones a través del portal, sin implementarlo mediante la API. Habla con el punto de contacto de tu proyecto para conocer las posibilidades.
| Encabezado | Valor |
|---|---|
Authorization | Bearer {token} — un token de acceso válido. |
{
"phone": "NOTIFICATION_PHONE",
"email": "NOTIFICATION_EMAIL"
}
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
phone | string | sí | Número de teléfono al que enviar la notificación. |
email | string | sí | Dirección de correo electrónico a la que enviar la notificación. |
{
"id": "b50ee24c-71eb-4a5d-ade1-41c48b44c240",
"link": "https://aces.so/example"
}
| Campo | Descripción |
|---|---|
id | ID único de la notificación generada. |
link | Enlace generado para la notificación. |
Para respuestas de error, consulta Errores — Reenvío de la notificación de la transacción.