Create order

Requires an active API credential with the orders:create permission. Send the complete recipient object advertised by the catalog. A missing Mobile Legends zone_id returns 422 validation_failed with error.details.recipient including 'is missing zone_id'; no order or fulfillment is created. The live examples use illustrative UUIDs: replace product_id with the top-level id returned by your live catalog. With a sandbox credential, product_id selects the static response scenario. Unknown non-blank sandbox product IDs default to the success response.

POST

https://cardzone.ai/api/b2b/v1/orders

Authorization

BearerAuth
HTTP
required

Request body JSON required

product_id
string
required
Sellable variant UUID: use the id returned by the products endpoint.

For sandbox keys, this selects the static response scenario:
- 018f0000-0000-7000-8000-000000000001 (sandbox-success-voucher): Static sandbox product that returns a fulfilled voucher order. Poll it with order_id 1CAYVN8V9qVvrLwnnSZsPE.
- 018f0000-0000-7000-8000-000000000002 (sandbox-wallet-topup-required): Static sandbox product that returns an action-required wallet order. Poll it with order_id 1CAYVN8V9qVvrLwnnSZsPF.
- 018f0000-0000-7000-8000-000000000003 (sandbox-merchant-attention-required): Static sandbox product that returns a fulfillment action-required order. Poll it with order_id 1CAYVN8V9qVvrLwnnSZsPG.
- 018f0000-0000-7000-8000-000000000004 (sandbox-manual-review-required): Static sandbox product that returns a manual-review action-required order. Poll it with order_id 1CAYVN8V9qVvrLwnnSZsPH.
- 018f0000-0000-7000-8000-000000000005 (sandbox-failed-order): Static sandbox product that returns a failed fulfillment response. Poll it with order_id 1CAYVN8V9qVvrLwnnSZsPJ.
format: uuid
quantity
integer
required
minimum: 1
merchant_order_ref
optional
string
or null
Optional store-scoped merchant order reference. Reusing the same value for the same store returns 409 merchant_order_ref_already_used and does not create another order. If you lose the create response, pass this value as {id} when polling order status.

maxLength: 128
recipient
optional
object
For voucher products, name/email/mobile are optional delivery details. For top-ups, send every canonical key advertised in recipient_fields by the catalog. PUBG normally requires player_id; Mobile Legends requires player_id and zone_id. Other products may require region_id or arbitrary configured safe keys. Send values as nonblank strings to preserve leading zeros. Missing and unconfigured fields return 422 validation_failed before order creation or fulfillment. Never substitute provider-specific keys such as userId or account_id unless that exact canonical key is configured on the Product.
- name
  optional
  string
- email
  optional
  string
  format: email
- mobile
  optional
  string
- player_id
  optional
  string
- zone_id
  optional
  string
- server_id
  optional
  string
- region_id
  optional
  string
- account_tag
  optional
  string
}
webhook_url
optional
string
or null
Optional HTTPS callback URL for this order.

format: uri

Example requests

{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa1",
  "quantity": 1,
  "recipient": {
    "player_id": "00123456789"
  }
}

{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa2",
  "quantity": 1,
  "recipient": {
    "player_id": "12345678",
    "zone_id": "1234"
  }
}

{
  "product_id": "018f7b75-0194-726a-9814-e26efa39dfa3",
  "quantity": 1,
  "recipient": {
    "player_id": "00123",
    "region_id": "eu",
    "account_tag": "main"
  }
}

Returns

201

Order accepted. The returned status may be processing, fulfilled, action_required, failed, or canceled.

JSON

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.

401

Missing, revoked, or unknown API key. A live key also gets this while its store is inactive, or until the store's business verification is approved and its primary user's email is verified.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

403

forbidden when the API credential lacks the required permission, or insufficient_store_wallet_balance when a live key's store does not meet the wallet requirement.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

404

The product cannot be ordered: error.code is validation_failed and error.details is product_not_found (unknown or deleted, hidden, out of stock, or no way to fulfill it for this store) or payment_option_not_found (no active price). error.product_status is out_of_stock or unavailable when the product exists.

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

409

merchant_order_ref has already been used for this store

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}

422

Validation failed

JSON

error
object
required
- code
  string
  required
- message
  string
  required
- details
  optional
  unknown
  Optional field-level validation details
- product_status
  optional
  out_of_stock
  or
  unavailable
  Present on 404 product errors when the product exists but cannot be ordered: out_of_stock or unavailable, with the same meaning as the catalog status. Absent when the product id is unknown or deleted.
}