> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Reservas de pago contra entrega

> El comprador paga antes de recibir su pedido, el dinero queda apartado y se libera cuando tu repartidor confirma la entrega con un QR

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

```bash
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:

```json
"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.

```bash
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" }'
```

| Respuesta                 | Qué significa                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `200`                     | Entrega confirmada. `payment_hold.status` es `released`. Repetir la llamada responde lo mismo. |
| `409` `not_held`          | El checkout no pidió reserva, aún no se paga o ya se devolvió.                                 |
| `409` `expired`           | Venció antes de la confirmación; el dinero regresa al comprador.                               |
| `422` `invalid_code`      | El código no coincide.                                                                         |
| `422` `too_many_attempts` | Hubo 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

| Evento                  | Cuándo                                                |
| ----------------------- | ----------------------------------------------------- |
| `payment_hold.released` | Se confirmó la entrega; el dinero está en tu balance. |
| `payment_hold.expired`  | Venció 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.