Skip to navigation

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

  1. Creas un checkout con payment_hold. Pon en metadata tu identificador del pedido, por ejemplo el número de guía.
  2. Le envías el checkout_url al comprador, por ejemplo por WhatsApp antes de que salga el repartidor.
  3. 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.
  4. 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}/release con su contenido.
  5. El dinero pasa a tu balance y recibes payment_hold.released, con tu metadata para 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

curl -X POST https://app.recurrente.com/api/checkouts \
-H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [{ "name": "Zapatos", "currency": "GTQ", "amount_in_cents": 40000, "quantity": 1 }],
"metadata": { "guia": "CE-1042" },
"payment_hold": { "expires_in_hours": 72 }
}'

La respuesta incluye:

"payment_hold": {
"status": "awaiting_payment",
"expires_in_hours": 72,
"expires_at": null,
"released_at": null
}
  • expires_in_hours va 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.

curl -X POST https://app.recurrente.com/api/checkouts/ch_lmgbvesmihkqzma3/release \
-H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "482913" }'
RespuestaQué significa
200Entrega confirmada. payment_hold.status es released. Repetir la llamada responde lo mismo.
409 not_heldEl checkout no pidió reserva, aún no se paga o ya se devolvió.
409 expiredVenció antes de la confirmación; el dinero regresa al comprador.
422 invalid_codeEl código no coincide.
422 too_many_attemptsHubo 10 códigos incorrectos; la reserva ya no acepta ninguno.

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

EventoCuándo
payment_hold.releasedSe confirmó la entrega; el dinero está en tu balance.
payment_hold.expiredVenció sin confirmación; se le devuelve al comprador.

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:

  1. Crea el checkout con payment_hold y tu llave del Sandbox.
  2. Abre el checkout_url y paga con la tarjeta de prueba. El comprobante muestra el QR y el código.
  3. Llama a POST /checkouts/{checkout_id}/release con ese código y recibe payment_hold.released.
  4. Para probar el vencimiento, crea una reserva con expires_in_hours: 24, págala y espera: al vencer recibes payment_hold.expired y el pago queda reembolsado.