Skip to navigation

Cash-on-delivery payment holds

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

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:

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

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" }'
ResponseWhat it means
200Delivery confirmed. payment_hold.status is released. Repeating the call returns the same.
409 not_heldThe checkout didn’t ask for a hold, isn’t paid yet, or was already refunded.
409 expiredIt expired before the confirmation; the money goes back to the buyer.
422 invalid_codeThe code doesn’t match.
422 too_many_attemptsThere 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

EventWhen
payment_hold.releasedThe delivery was confirmed; the money is in your balance.
payment_hold.expiredIt 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.