Reservas de pago contra entrega
Una reserva de pago reemplaza el efectivo contra entrega sin pedirle al comprador que confíe a ciegas: paga antes de que llegue el paquete, pero el dinero no queda disponible en tu balance hasta que tu repartidor confirma la entrega escaneando el QR del comprador. Si nadie la confirma a tiempo, se le devuelve el monto completo al comprador, a la misma cuenta o billetera desde la que pagó.
Antes de pagar, la página le dice al comprador cuánto paga, quién lo recibe, hasta cuándo dura la reserva y cómo se le devuelve si no llega su pedido.
Cómo funciona
- Creas un checkout con
payment_hold. Pon enmetadatatu identificador del pedido, por ejemplo el número de guía. - Le envías el
checkout_urlal comprador, por ejemplo por WhatsApp antes de que salga el repartidor. - El comprador paga. Recibes el webhook de pago y el checkout muestra
payment_hold.status: "held". Tu sistema ya sabe que el repartidor no debe cobrar efectivo. - Al entregar, quien recibe muestra el QR (del comprobante, del correo o del enlace que le compartió el comprador). Tu app del repartidor lo escanea y llama a
POST /checkouts/{checkout_id}/releasecon su contenido. - El dinero pasa a tu balance y recibes
payment_hold.released, con tumetadatapara amarrarlo al pedido.
Si nadie confirma la entrega antes de payment_hold.expires_at, recibes payment_hold.expired y el comprador recibe su dinero de vuelta. El dinero nunca estuvo disponible en tu balance, así que no se te descuenta nada.
Crear una reserva
La respuesta incluye:
expires_in_hoursva de 24 a 168 y empieza a correr cuando el comprador paga. Envía{}para el valor por defecto de 72 horas.- Para rutas que tardan más, como las del interior, dale más tiempo a ese checkout:
{ "expires_in_hours": 120 }. - Solo aplica a cobros únicos.
Métodos de pago
Una reserva ofrece transferencia bancaria en Guatemala, dólares digitales (USDT), Balance Recurrente y Akisí. No ofrece tarjeta.
Confirmar la entrega
El comprador ve en su comprobante un QR y, debajo, un código de 6 dígitos para cuando la cámara no lo lee. El código también le llega en su correo de confirmación, y puede compartir el QR con quien vaya a recibir el paquete (un familiar, alguien en la oficina): quien lo tenga puede recibir. Solo lo ven el navegador desde el que pagó, su correo y quien él elija: aunque tú tengas el enlace del checkout, no ves el código.
El código nunca aparece en la API ni en los webhooks: es la prueba de que el repartidor estuvo frente al comprador.
Si la reserva vence
- Transferencia bancaria en Guatemala: se devuelve a la cuenta de la que vino, después de confirmar con el banco que está a nombre de quien pagó.
- Dólares digitales: se devuelven a la dirección desde la que se enviaron, en la misma moneda.
- Balance Recurrente: vuelven al balance del comprador al instante.
- Akisí, o si no se puede devolver a la cuenta de origen: le escribimos al comprador para que elija una cuenta bancaria a su nombre o una billetera USDT.
El comprador recibe el monto completo que pagó. Las comisiones de esa transacción las absorbe Recurrente.
Webhooks
Los dos traen payment_hold y el checkout completo, con tu metadata.
Probar en un Sandbox
En un Sandbox la reserva funciona igual, sin mover dinero real. Ahí la reserva también ofrece la tarjeta de prueba 4242 4242 4242 4242, para que puedas recorrer el flujo completo:
- Crea el checkout con
payment_holdy tu llave del Sandbox. - Abre el
checkout_urly paga con la tarjeta de prueba. El comprobante muestra el QR y el código. - Llama a
POST /checkouts/{checkout_id}/releasecon ese código y recibepayment_hold.released. - Para probar el vencimiento, crea una reserva con
expires_in_hours: 24, págala y espera: al vencer recibespayment_hold.expiredy el pago queda reembolsado.

