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.

ℹ️

Usa un identificador idempotente x-app-request-id (UUID v4) y conservá su valor. Si necesitás reintentar o cancelar la intención, utilizá el mismo valor para evitar duplicados y mantener la trazabilidad end-to-end.

Endpoints disponibles

Para trabajar con intenciones de pago, disponés de los siguientes endpoints:

1. Crear intención de pago

POST /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 /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 /cloud-terminals/payment-intentions/{requestId}

Obtiene el estado detallado y resultado de una intención, incluyendo datos de la transacción, impuestos y información de la tarjeta.

4. Obtener intenciones de pago

GET /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.

Flujo de trabajo recomendado

Crear la intención con un x-app-request-id único (UUID v4)
Consultar periódicamente el estado hasta que cambie de PENDING
Cancelar si es necesario antes de que se complete

⚠️

Los estados EXECUTED 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.

Estados de intenciones de pago

Valor	Descripción
`CREATED`	Creado.
`PENDING`	Pendiente.
`DELIVERED`	Entregado.
`EXECUTED`	Ejecutado (estado final).
`NOT_DELIVERED`	No entregado (estado final de error).

Consideraciones importantes

Idempotencia: Usá el mismo x-app-request-id para crear y cancelar
Ownership: Los IDs deben pertenecer a la cuenta del token

Administración de Webhooks Token de Customer