Store wallet

This page explains how your store wallet pays for orders, and what happens when the balance is too low.

Cardzone does not charge your customer. You sell to your customers in any way you choose. Cardzone takes the money for each order from your store wallet, at the product’s purchase_price. You recharge the store wallet (add money to it) in the Cardzone dashboard.

The minimum balance for live API keys

Live API keys need one of these:

• an enabled postpaid store wallet (you pay later), or
• a prepaid balance (money you add first) of at least 100 SAR.

If you have neither, live endpoints return this error:

{
  "error": {
    "code": "insufficient_store_wallet_balance",
    "message": "Live API access needs an enabled postpaid wallet or a prepaid wallet balance of at least 100 SAR",
    "details": { "minimum_prepaid_balance": { "amount": "100.00", "currency": "SAR" } }
  }
}

These calls still work below the minimum. So you can always check and settle the orders you already placed:

• Get balance
• Poll order status
• Cancel order

Player lookups use their own error code for the same rule: player_lookup_requirements_not_met. Sandbox API keys never have a store wallet requirement.

Wallet-blocked orders

Sometimes the store wallet can’t pay for an order during fulfillment. The order does not fail. Instead:

1. The order moves to action_required, with a wallet_topup_required action.
2. The action’s message gives the total amount needed for all wallet-blocked orders in the store.

"actions": [
  {
    "type": "wallet",
    "code": "wallet_topup_required",
    "message": "Recharge 50 SAR to resume fulfillment for all wallet-blocked orders."
  }
]

After you recharge the store wallet, fulfillment continues by itself. The order then moves on to fulfilled or another status. You don’t need to send anything again.