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. Consultar intención de pago
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.
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
Consideraciones importantes
- Idempotencia: Usá el mismo
x-app-request-idpara crear y cancelar - Ownership: Los IDs deben pertenecer a la cuenta del token