Retry safely

This page shows how to retry order requests without buying the same item twice. Read it before you write your order code.

Here is the problem. Sometimes your POST /orders request reaches Cardzone, and Cardzone accepts the order and charges for it. But a network error stops the response from reaching you. If you then send the request again with no plan, you buy the item twice.

A request is safe to retry (idempotent) when sending it twice has the same result as sending it once. merchant_order_ref makes order creation safe to retry.

Send a `merchant_order_ref` with every order

merchant_order_ref is your own ID for the order. The API accepts orders without it, but then you can’t retry safely. So always send one.

Rules for merchant_order_ref:

It can be up to 128 characters long.
It must be unique across every order in your store.
Use the order ID or line ID from your own system.
Add a prefix that only your API integration uses, such as api-.

Why the prefix? Cardzone’s other order channels also store merchant_order_ref values. If one of them uses the same value, your API order is blocked (see the 409 step below).

{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "quantity": 1,
  "merchant_order_ref": "shop-order-1001",
  "recipient": { "player_id": "00123456789" }
}

If you send the same merchant_order_ref again, Cardzone never creates a second order. Instead, it returns this body:

{
  "error": {
    "code": "merchant_order_ref_already_used",
    "message": "merchant_order_ref has already been used for this store"
  }
}

The HTTP status is 409 Conflict. Treat it as “this order already exists”. It is not a failure.

Cardzone checks only the merchant_order_ref. It doesn’t compare the rest of the body. So if you reuse a merchant_order_ref for a different product, you also get 409.

When the create response is lost

Follow these steps when the create response is lost (a timeout, a connection error, or a 5xx), or when you get a 409:

Retry with the same merchant_order_ref, never a new one
A new merchant_order_ref creates a new order. Create the merchant_order_ref once, when your customer checks out. Reuse it on every attempt. The only exception is in the last step below.
On a timeout or 5xx, look up the order by your merchant_order_ref
GET /api/b2b/v1/orders/shop-order-1001 accepts your merchant_order_ref in place of the order_id. A 200 means the order exists. Save its order_id and continue.
On 404, create the order again with the same merchant_order_ref
Cardzone never created the first order. It is safe to retry, because the merchant_order_ref still protects you from duplicates.
On 409, look it up too
A 409 merchant_order_ref_already_used means an order with that merchant_order_ref exists. Look it up by merchant_order_ref, the same way as after a timeout. If that lookup returns 404, the merchant_order_ref belongs to an order from another channel, not an API order. In that case, create the order again with a new merchant_order_ref.

Which errors to retry

A 4xx status means a problem on your side. A 5xx status means an error on Cardzone’s side.

Response	Retry?
Timeout, connection error, `5xx`	Yes. Use the steps above. Wait longer before each new try (exponential backoff).
`429 rate_limited`	Yes, after a pause.
`409 merchant_order_ref_already_used`	No. Look up the order by `merchant_order_ref`.
`401`, `403`	No. First fix the API key, its permissions, or the store wallet balance.
`404` with `details: "product_not_found"`, `422 validation_failed`	No. Fix the request, or refresh your catalog.

Send a merchant_order_ref with every order

When the create response is lost

Which errors to retry

Send a `merchant_order_ref` with every order