---
title: "B2B API order webhook"
---

> 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.

# B2B API order webhook

Path: Cardzone B2B API

`POST b2b.order.created`

_Webhook._

Sent when the B2B API creates an order. This is not the final success signal.

## Request body

_Required._

- `event` (`b2b.order.created.event`; string, required)
  - one of `"b2b.order.created"`
- `event_id` (`b2b.order.created.event_id`; string, required)
- `platform` (`b2b.order.created.platform`; string, required)
  - example `"cardzone"`
- `source` (`b2b.order.created.source`; string, required)
  - example `"b2b_api"`
- `created_at` (`b2b.order.created.created_at`; string, required)
  - format `date-time`
- `store` (`b2b.order.created.store`; object, required)
- `order` (`b2b.order.created.order`; object, required) — Live responses omit keys that have no value instead of sending `null`.
  - `order_id` (`b2b.order.created.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` (`b2b.order.created.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` (`b2b.order.created.order.product_id`; string, required, nullable)
    - format `uuid`
  - `quantity` (`b2b.order.created.order.quantity`; integer, required)
  - `actions` (`b2b.order.created.order.actions`; array<object>, required) — Actions required from the API consumer. Empty when no action is needed.
    - `type` (`b2b.order.created.order.actions.type`; string, required)
      - one of `"wallet"`, `"fulfillment"`
    - `code` (`b2b.order.created.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` (`b2b.order.created.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` (`b2b.order.created.order.created_at`; string, required)
    - format `date-time`
  - `merchant_order_ref` (`b2b.order.created.order.merchant_order_ref`; string, optional, nullable) — Merchant order reference supplied on create, when present.
  - `product_code` (`b2b.order.created.order.product_code`; string, optional, nullable)
  - `purchase_price` (`b2b.order.created.order.purchase_price`; object, optional)
    - `amount` (`b2b.order.created.order.purchase_price.amount`; string, required) — Decimal amount as a string
      - example `"12.00"`
    - `currency` (`b2b.order.created.order.purchase_price.currency`; string, required)
      - example `"SAR"`
  - `recommended_retail_price` (`b2b.order.created.order.recommended_retail_price`; object, optional)
    - `amount` (`b2b.order.created.order.recommended_retail_price.amount`; string, required) — Decimal amount as a string
      - example `"12.00"`
    - `currency` (`b2b.order.created.order.recommended_retail_price.currency`; string, required)
      - example `"SAR"`
  - `code` (`b2b.order.created.order.code`; string, optional, nullable) — First delivered voucher code/PIN when available
  - `codes` (`b2b.order.created.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` (`b2b.order.created.order.failure_reason`; string, optional, nullable) — Backward-compatible human-readable failure summary. Provider messages and responses are never exposed here.
  - `failure_code` (`b2b.order.created.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"`

## Example request

```json
{
  "event": "b2b.order.created",
  "event_id": "b2b.order.created:1CBDzqwiovwVrtFk6nZ1Aw",
  "platform": "cardzone",
  "source": "b2b_api",
  "created_at": "2026-05-18T00:30: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": "processing",
    "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"
    },
    "codes": [],
    "actions": [],
    "created_at": "2026-05-18T00:29:58+03:00"
  }
}
```

## Responses

### 200

Return any 2xx status to acknowledge receipt.


Source: https://docs.cardzone.ai/reference/webhooks/b2b.order.created/index.md