This page shows how to handle an order whose status is action_required. If you haven’t yet, read Order lifecycle first.
action_required means the order is paused. It is not lost. Each entry in actions[] says why the order is paused.
- Your code MUST make decisions based on
typeandcode. - NEVER parse
message. It is text for people, and it can change or be translated.
Try each action
Pick a scenario. The sandbox returns the same actions[] shape that a live order returns:
POSTWhat each action means
Your store wallet could not pay for fulfillment. message gives the total amount to recharge for all wallet-blocked orders in the store. For example: “Recharge 50 SAR to resume fulfillment for all wallet-blocked orders.”
What to do: alert the person who recharges the store wallet, and tell the customer there is a short delay. After the store wallet is recharged, fulfillment continues without any more API calls. You get a status_changed webhook as the order moves on.
Fulfillment has not delivered within 15 minutes. Open the order in the Cardzone dashboard to see what is pending. If it stays blocked, contact Cardzone support and give them the order_id.
Cardzone is reviewing the order before it continues. You don’t need to send anything. Keep the customer informed, and keep polling or listening for webhooks. The review ends in fulfilled, failed, or another status.
Example handler
This function runs for every order update, from a webhook or a poll:
function onOrderUpdate(order) {
switch (order.status) {
case "fulfilled":
return markPaidAndDeliver(order);
case "failed":
return notifyFailure(order, order.failure_code);
case "canceled":
return releaseOrder(order);
case "action_required":
for (const action of order.actions) {
if (action.code === "wallet_topup_required") alertFinance(action.message);
else if (action.code === "manual_review_required") continue; // nothing to do but wait
else alertSupport(order.order_id, action.message); // merchant_attention_required, or a code you don't know yet
}
return showDelayed(order);
default:
return showPending(order); // processing
}
}