Intención de pago

Una intención de pago es una solicitud de cobro que se envía a la terminal del comercio a distancia. De esta manera el importe y los datos del negocio llegan al dispositivo sin que la persona operadora tenga que introducirlos manualmente. La persona usuaria solo acerca o inserta su tarjeta en la terminal para confirmar el monto, ya que la orden de cobro se envía desde tu backend y no requiere interacción adicional en el dispositivo.

Configuración previa

Para trabajar con intenciones de pago es necesario habilitar la terminal en modo “intenciones de pago” desde su configuración. Esto activa la recepción de solicitudes y hace que la terminal escuche las operaciones enviadas por tu backend.

ℹ️

El request_id de la intención lo genera el servidor y se devuelve en el body de la respuesta al crearla. Conserva ese valor para consultar o cancelar la intención.

⚠️

Crear o cancelar una intención de pago requiere que la terminal esté CONECTADA. Si no hay terminal conectada, la API responde 422 y no envía la intención.

Endpoints disponibles

Para trabajar con intenciones de pago, dispones de los siguientes endpoints:

1. Crear intención de pago

POST /v1/cloud-terminals/payment-intentions

Envía una solicitud de cobro a la terminal. La persona usuaria solo necesita acercar o insertar su tarjeta para confirmar el monto.

2. Cancelar intención de pago

DELETE /v1/cloud-terminals/payment-intentions

Cancela una intención antes de que se complete la transacción. La terminal vuelve a la pantalla de espera.

3. Obtener intención de pago realizada

GET /v1/cloud-terminals/payment-intentions/{requestId}

Obtiene los datos de una intención (type, status, created_at y data) y, cuando ya existe una transacción asociada, el objeto transaction_details con los datos de la transacción, incluyendo impuestos e información de la tarjeta. Mientras no exista una transacción, la respuesta no incluye transaction_details. Se deben enviar customerId y merchantId.

4. Obtener intenciones de pago

GET /v1/cloud-terminals/payment-intentions

Obtiene el listado de intenciones de pago (y cancelaciones) enviadas, con filtros por terminal, requestId, rango de fechas, flow y paginación.

5. Consultar terminales cloud

GET /v1/cloud-terminals/clients y GET /v1/cloud-terminals/clients/{serialCode}

Permiten verificar que una terminal esté conectada y suscrita a PAYMENT_INTENTIONS antes de crear una intención.

Flujo de trabajo recomendado

Crear la intención y conservar el request_id devuelto en el body
Consultar periódicamente el listado de intenciones (filtrando por requestId) hasta un estado final (EXECUTED, CANCELLED o NOT_DELIVERED). Es esperable pasar por PROCESSING cuando la terminal recibió la solicitud de intención de pago
Cancelar si es necesario antes de que se complete

Ciclo típico de una intención de pago:

CREATED → PENDING → DELIVERED → PROCESSING → EXECUTED o CANCELLED

⚠️

Los estados EXECUTED, CANCELLED y NOT_DELIVERED son estados finales: una vez que la intención llega a uno de ellos, no puede transicionar a ningún otro estado.

ℹ️

Si una intención permanece en PROCESSING más de 3 minutos, el sistema puede iniciar una cancelación automática. Cuando esa cancelación se liquida, la intención de pago original pasa a CANCELLED.

Estados de intenciones de pago

Valor	Descripción
`CREATED`	Creado.
`PENDING`	Pendiente de entrega a la terminal.
`DELIVERED`	Entregado a la terminal.
`PROCESSING`	La terminal recibió la solicitud de intención de pago.
`EXECUTED`	Cobro confirmado por la operación (estado final).
`CANCELLED`	Intención anulada, o cancelada automáticamente si tras 3 minutos no se recibió la confirmación del cobro (estado final).
`NOT_DELIVERED`	No entregado a la terminal (estado final de error).

Cuando una cancelación llega a EXECUTED o NOT_DELIVERED, la intención de pago relacionada (mismo requestId) pasa a CANCELLED.

Consideraciones importantes

Identificador: Usa el request_id devuelto al crear la intención para consultarla y cancelarla.
Ownership: Los IDs deben pertenecer a la cuenta del token
Terminal conectada: Las escrituras (crear/cancelar) exigen que la terminal esté conectada; de lo contrario la API responde 422

Administración de Webhooks Introducción