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.

URL base

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.

peligro

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.

peligro

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.

Encabezados

Encabezado	Valor
`Authorization`	`Bearer {token}` — un token de acceso válido.

Cuerpo

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

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

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

advertencia

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.

Encabezados

Encabezado	Valor
`Authorization`	`Bearer {token}` — un token de acceso válido.

200 OK

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

advertencia

El conjunto probatorio solo se puede generar para transacciones aprobadas.

peligro

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.

Encabezados

Encabezado	Valor
`Authorization`	`Bearer {token}` — un token de acceso válido.

200 OK

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

nota

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.

Encabezados

Encabezado	Valor
`Authorization`	`Bearer {token}` — un token de acceso válido.

Cuerpo

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

200 OK

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

Antes de empezar​

Crear transacción​

Obtener estado de la transacción​

Obtener conjunto probatorio de la transacción​

Reenviar notificación de la transacción​

Antes de empezar

Crear transacción

Obtener estado de la transacción

Obtener conjunto probatorio de la transacción

Reenviar notificación de la transacción