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
- Create a checkout with
payment_hold. Put your order identifier inmetadata, for example the tracking number. - Send the buyer the
checkout_url, for example over WhatsApp before the driver leaves. - 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. - 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}/releasewith its content. - The money moves to your balance and you receive
payment_hold.released, with yourmetadatato 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
The response includes:
expires_in_hoursgoes 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.
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
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:
- Create the checkout with
payment_holdand your Sandbox key. - Open the
checkout_urland pay with the test card. The receipt shows the QR and the code. - Call
POST /checkouts/{checkout_id}/releasewith that code and receivepayment_hold.released. - To test expiry, create a hold with
expires_in_hours: 24, pay it and wait: when it expires you receivepayment_hold.expiredand the payment is refunded.

