---
title: "B2bApiOrderWebhookPayload"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.cardzone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# B2bApiOrderWebhookPayload

Path: Cardzone B2B API

Order-created notification for B2B API orders. This is not the final success signal; the `order` object matches the polling response.

## Fields

- `event` (`B2bApiOrderWebhookPayload.event`; string, required)
  - one of `"b2b.order.created"`
- `event_id` (`B2bApiOrderWebhookPayload.event_id`; string, required)
- `platform` (`B2bApiOrderWebhookPayload.platform`; string, required)
  - example `"cardzone"`
- `source` (`B2bApiOrderWebhookPayload.source`; string, required)
  - example `"b2b_api"`
- `created_at` (`B2bApiOrderWebhookPayload.created_at`; string, required)
  - format `date-time`
- `store` (`B2bApiOrderWebhookPayload.store`; object, required)
- `order` (`B2bApiOrderWebhookPayload.order`; object, required) — Live responses omit keys that have no value instead of sending `null`.
  - `order_id` (`B2bApiOrderWebhookPayload.order.order_id`; string, required) — Cardzone order identifier. This is a reversible Base58 representation of the internal UUID.
    - minLength 22; maxLength 22; pattern `^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$`
  - `status` (`B2bApiOrderWebhookPayload.order.status`; string, 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.
    - one of `"processing"`, `"fulfilled"`, `"action_required"`, `"failed"`, `"canceled"`
  - `product_id` (`B2bApiOrderWebhookPayload.order.product_id`; string, required, nullable)
    - format `uuid`
  - `quantity` (`B2bApiOrderWebhookPayload.order.quantity`; integer, required)
  - `actions` (`B2bApiOrderWebhookPayload.order.actions`; array<object>, required) — Actions required from the API consumer. Empty when no action is needed.
    - `type` (`B2bApiOrderWebhookPayload.order.actions.type`; string, required)
      - one of `"wallet"`, `"fulfillment"`
    - `code` (`B2bApiOrderWebhookPayload.order.actions.code`; string, required) — Machine-readable action the API consumer should handle.
      - one of `"wallet_topup_required"`, `"merchant_attention_required"`, `"manual_review_required"`
    - `message` (`B2bApiOrderWebhookPayload.order.actions.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.
      - example `"Recharge 75 SAR to resume fulfillment for all wallet-blocked orders."`
  - `created_at` (`B2bApiOrderWebhookPayload.order.created_at`; string, required)
    - format `date-time`
  - `merchant_order_ref` (`B2bApiOrderWebhookPayload.order.merchant_order_ref`; string, optional, nullable) — Merchant order reference supplied on create, when present.
  - `product_code` (`B2bApiOrderWebhookPayload.order.product_code`; string, optional, nullable)
  - `purchase_price` (`B2bApiOrderWebhookPayload.order.purchase_price`; object, optional)
    - `amount` (`B2bApiOrderWebhookPayload.order.purchase_price.amount`; string, required) — Decimal amount as a string
      - example `"12.00"`
    - `currency` (`B2bApiOrderWebhookPayload.order.purchase_price.currency`; string, required)
      - example `"SAR"`
  - `recommended_retail_price` (`B2bApiOrderWebhookPayload.order.recommended_retail_price`; object, optional)
    - `amount` (`B2bApiOrderWebhookPayload.order.recommended_retail_price.amount`; string, required) — Decimal amount as a string
      - example `"12.00"`
    - `currency` (`B2bApiOrderWebhookPayload.order.recommended_retail_price.currency`; string, required)
      - example `"SAR"`
  - `code` (`B2bApiOrderWebhookPayload.order.code`; string, optional, nullable) — First delivered voucher code/PIN when available
  - `codes` (`B2bApiOrderWebhookPayload.order.codes`; array<string>, optional) — 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` (`B2bApiOrderWebhookPayload.order.failure_reason`; string, optional, nullable) — Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
  - `failure_code` (`B2bApiOrderWebhookPayload.order.failure_code`; string, optional, nullable) — 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.
    - one of `"fulfillment_failed"`, `"player_id_incorrect"`


Source: https://docs.cardzone.ai/reference/schemas/B2bApiOrderWebhookPayload/index.md