# Cash-on-delivery order confirmation

> Confirm the customer's number with a code before accepting a cash-on-delivery order, to cut fake orders and returns.

Fake and mistyped numbers are the main cost of cash-on-delivery: the courier drives out and nobody answers. Confirming the number with a code before the order is accepted removes most of them.

## Two ways to do it

| | Before placing the order | After placing the order |
|---|---|---|
| When | At checkout, before "Place order" | Right after the order is created |
| How | The checkout asks for the code; the order can't be placed until it's confirmed | The order is created as "unconfirmed"; it ships only once the customer types the code (on the thank-you page or a link) |
| Best for | Your own checkout, WooCommerce | Platforms where you can't change checkout (e.g. Shopify), orders taken by phone or chat |

## Before placing the order (recommended)

1. The customer fills in the checkout and chooses cash on delivery.
2. Your **server** sends a code with `purpose: "order"`, using an `Idempotency-Key` tied to the cart (e.g. `cart-8812-otp-1`), so a double click or a retry doesn't send twice.
3. Keep the verification `id` **and the normalized number** in the server-side session, never in a hidden form field.
4. The customer types the code; your server checks it. On `valid: true`, store the verified number in the session.
5. When the order is submitted, your server refuses it unless the order's phone **equals** the verified number in the session. This stops a customer from verifying one number and changing it afterwards.
6. Save on the order that the phone was verified (and when), so your team can see it.

```js
// On "Place order", server side:
if (order.paymentMethod === "cod" && normalizePhone(order.phone) !== session.verifiedPhone) {
  return refuse("Please confirm your mobile number first.");
}
```

The [WooCommerce plugin](/docs/examples/woocommerce) is a complete implementation of this flow.

## After placing the order

1. Create the order with a status or tag like "awaiting phone confirmation" and don't ship it.
2. Send the code (`purpose: "order"`, `Idempotency-Key: order-<id>-otp-1`) and show a code box on the confirmation page.
3. On `valid: true`, mark the order confirmed. Orders still unconfirmed after a few hours can be cancelled or called by your team.

## Without your own screen: verification links

If you can't add a code box anywhere (Shopify, an order taken by phone or chat, a no-code tool), create a [verification link](/docs/verification-links) when the order comes in:

```json
POST /api/v1/verify/links
{ "phone": "0599123456", "purpose": "order", "reference": "#1042", "delivery": "sms" }
```

OTP.ps texts the customer "confirm your order" with a link; they open it and press Confirm. Your [webhook](/docs/webhooks) receives `link.approved` with `reference: "#1042"`, and you ship. If it expires (`link.expired`), call the customer or cancel the order.

## Good practice

- Only ask for a code for cash-on-delivery (paid orders don't need it).
- Use `locale` to match the shop's language.
- Limit sends per cart and per visitor on your side (e.g. 3 codes per cart), on top of OTP.ps's limits.
- If OTP.ps answers `insufficient_balance` or is unreachable, decide in advance: block COD, or accept the order as "unconfirmed" and alert your team. Don't silently skip the check.
