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

# Cash-on-delivery payment holds

> The buyer pays before receiving their order, the money is set aside, and it's released when your driver confirms the delivery with a QR

A payment hold replaces cash on delivery without asking the buyer to trust blindly: they pay before the package arrives, but the money **isn't available in your balance** until your driver confirms the delivery by scanning the buyer's QR. If nobody confirms it in time, the buyer gets the full amount back, to the same account or wallet they paid from.

Before paying, the page tells the buyer how much they pay, who receives it, how long the hold lasts and how it's returned if their order doesn't arrive.

## How it works

1. Create a checkout with `payment_hold`. Put your order identifier in `metadata`, for example the tracking number.
2. Send the buyer the `checkout_url`, for example over WhatsApp before the driver leaves.
3. The buyer pays. You receive the payment webhook and the checkout shows `payment_hold.status: "held"`. Your system now knows the driver must not collect cash.
4. At delivery, whoever receives shows the QR (from the receipt, the email or the link the buyer shared). Your driver app scans it and calls `POST /checkouts/{checkout_id}/release` with its content.
5. The money moves to your balance and you receive `payment_hold.released`, with your `metadata` to match it to the order.

If nobody confirms the delivery before `payment_hold.expires_at`, you receive `payment_hold.expired` and the buyer gets their money back. The money was never available in your balance, so nothing is taken from you.

## Create a hold

```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": "Shoes", "currency": "GTQ", "amount_in_cents": 40000, "quantity": 1 }],
    "metadata": { "guia": "CE-1042" },
    "payment_hold": { "expires_in_hours": 72 }
  }'
```

The response includes:

```json
"payment_hold": {
  "status": "awaiting_payment",
  "expires_in_hours": 72,
  "expires_at": null,
  "released_at": null
}
```

* `expires_in_hours` goes from 24 to 168 and starts when the buyer pays. Send `{}` for the 72-hour default.
* For routes that take longer, such as rural ones, give that checkout more time: `{ "expires_in_hours": 120 }`.
* One-time payments only.

### Payment methods

A hold offers bank transfer in Guatemala, digital dollars (USDT), Recurrente Balance and Akisí. It doesn't offer cards.

## Confirm the delivery

The buyer's receipt shows a QR and, under it, a 6-digit code for when the camera can't read it. The code also arrives in the buyer's confirmation email, and the buyer can share the QR with whoever will receive the package (a relative, someone at the office): whoever has it can receive. Only the browser that paid, the buyer's email and whoever the buyer chooses see it: even though you have the checkout link, you don't see the code.

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

| Response                  | What it means                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| `200`                     | Delivery confirmed. `payment_hold.status` is `released`. Repeating the call returns the same. |
| `409` `not_held`          | The checkout didn't ask for a hold, isn't paid yet, or was already refunded.                  |
| `409` `expired`           | It expired before the confirmation; the money goes back to the buyer.                         |
| `422` `invalid_code`      | The code doesn't match.                                                                       |
| `422` `too_many_attempts` | There were 10 wrong codes; the hold no longer accepts any.                                    |

The code never appears in the API or in webhooks: it's the proof that the driver stood in front of the buyer.

## If the hold expires

* **Bank transfer in Guatemala:** it goes back to the account it came from, after the bank confirms the account belongs to whoever paid.
* **Digital dollars:** they go back to the address they were sent from, in the same currency.
* **Recurrente Balance:** it returns to the buyer's balance at once.
* **Akisí**, or when it can't go back to the source account: we write to the buyer so they choose a bank account in their name or a USDT wallet.

The buyer gets back the full amount they paid. Recurrente absorbs that transaction's fees.

## Webhooks

| Event                   | When                                                        |
| ----------------------- | ----------------------------------------------------------- |
| `payment_hold.released` | The delivery was confirmed; the money is in your balance.   |
| `payment_hold.expired`  | It expired without confirmation; it goes back to the buyer. |

Both carry `payment_hold` and the full `checkout`, with your `metadata`.

## Test in a Sandbox

In a Sandbox the hold works the same, without moving real money. There the hold also offers the test card `4242 4242 4242 4242`, so you can walk through the whole flow:

1. Create the checkout with `payment_hold` and your Sandbox key.
2. Open the `checkout_url` and pay with the test card. The receipt shows the QR and the code.
3. Call `POST /checkouts/{checkout_id}/release` with that code and receive `payment_hold.released`.
4. To test expiry, create a hold with `expires_in_hours: 24`, pay it and wait: when it expires you receive `payment_hold.expired` and the payment is refunded.