B2B API order status webhook

Sent when a B2B API order's public API status changes, or when Cardzone delivers replacement codes the store paid for. The order object matches GET /api/b2b/v1/orders/{id}.

POST

b2b.order.status_changed

Webhook

Request body JSON required

event
b2b.order.status_changed
required

event_id
string
required
Stable event identifier. Use this to dedupe webhook deliveries.
platform
string
required
source
string
required
created_at
string
required
format: date-time
store
object
required
order
object
required
Live responses omit keys that have no value instead of sending null.
- order_id
  string
  required
  Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.
  
  maxLength: 22 · minLength: 22 · pattern: ^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
- status
  processing
  or
  fulfilled
  or
  action_required
  or
  failed
  or
  canceled
  required
  processing: accepted or still fulfilling. fulfilled: successful; safe to mark the partner order successful. action_required: inspect actions and take the required action. failed: terminal failure; inspect failure_reason when present. Replacement codes the store paid for can still be added to codes, and a dashboard retry moves the order back to processing. canceled: terminal cancellation; no fulfillment action remains.
- product_id
  string
  or null
  required
  format: uuid
- quantity
  integer
  required
- actions
  array of
  object
  required
  Actions required from the API consumer. Empty when no action is needed.
  
  type
  wallet
  or
  fulfillment
  required
  code
  wallet_topup_required
  or
  merchant_attention_required
  or
  manual_review_required
  required
  Machine-readable action the API consumer should handle.
  
  message
  string
  required
  Human-readable action summary. Wallet actions include the aggregate additional top-up amount needed for all current wallet-blocked orders in the store.
- created_at
  string
  required
  format: date-time
- merchant_order_ref
  optional
  string
  or null
  Merchant order reference supplied on create, when present.
- product_code
  optional
  string
  or null
- purchase_price
  optional
  object
  amount
  string
  required
  Decimal amount as a string
  
  currency
  string
  required
- recommended_retail_price
  optional
  object
  amount
  string
  required
  Decimal amount as a string
  
  currency
  string
  required
- code
  optional
  string
  or null
  First delivered voucher code/PIN when available
- codes
  optional
  array of
  string
  All delivered voucher codes/PINs when available. Includes replacement codes Cardzone delivered and charged to the store, which can appear while status is failed.
- failure_reason
  optional
  string
  or null
  Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
- failure_code
  optional
  fulfillment_failed
  or
  player_id_incorrect
  or null
  Cardzone-owned terminal failure identifier. fulfillment_failed is the generic failure and player_id_incorrect means the submitted player ID was definitively rejected. Provider messages and responses are never exposed here.
}

Example request

{
  "event": "b2b.order.status_changed",
  "event_id": "b2b.order.status_changed:1CBDzqwiovwVrtFk6nZ1Aw:2",
  "platform": "cardzone",
  "source": "b2b_api",
  "created_at": "2026-05-18T00:33:00+03:00",
  "store": {
    "id": 42,
    "uuid": "018f7b72-91f9-7e0b-a6dc-8f9b2d42e901",
    "name": "Demo Store",
    "provider": "cardzone"
  },
  "order": {
    "order_id": "1CBDzqwiovwVrtFk6nZ1Aw",
    "merchant_order_ref": "merchant-order-10001",
    "status": "fulfilled",
    "product_id": "018f7b75-0194-726a-9814-e26efa39dfac",
    "product_code": "psn-sa-160",
    "quantity": 1,
    "purchase_price": {
      "amount": "380.00",
      "currency": "SAR"
    },
    "recommended_retail_price": {
      "amount": "400.00",
      "currency": "SAR"
    },
    "code": "PIN-123",
    "codes": [
      "PIN-123"
    ],
    "actions": [],
    "created_at": "2026-05-18T00:29:58+03:00"
  }
}

Returns

200

Return any 2xx status to acknowledge receipt.