Catalog and recipients

This page explains the product list (the catalog) and how to collect the customer’s account details for a top-up.

The catalog is a list of products. Each product is one item at one fixed amount, such as PUBG 60 UC or PlayStation Saudi 160 USD. To order a product, send its id as product_id.

Product fields you need

Field	What it is for
`id`	The `product_id` you send when you order.
`delivery_type`	`topup` adds credit to a game account. `voucher` returns a code or PIN in `codes[]`.
`recipient_fields`	The account fields a top-up needs, in the order you should show them. Empty for vouchers.
`player_lookup`	`true` when player lookup can show the account name before the customer orders.
`purchase_price`	What your store wallet pays for one unit.
`recommended_retail_price`	The price Cardzone suggests you charge your customer.
`status`	`available`, `out_of_stock`, or `unavailable`. See availability.
`product_code`	Cardzone’s internal code. Give it to support when you ask about a product. Don’t parse it.
`description`	Optional HTML in the request language. Cardzone cleans (sanitizes) it first. It can have paragraphs, lists, links, and images. Show it as HTML, or remove the tags. If it is missing, leave it out of your page.

Amounts are decimal strings with a currency, such as {"amount": "12.00", "currency": "SAR"}. Parse them as decimals, not floats. Floating-point numbers can round money amounts wrongly.

List products returns your whole catalog in one response. It is sorted by category name, then by product name. There is no pagination (no pages) and no sort parameter. List categories is sorted by name.

Build the form from `recipient_fields`

A recipient is the person who receives the order. For a top-up, recipient holds the player’s game account details. For a voucher, it can hold contact details.

NEVER hardcode which games need which fields. Instead, build the form from recipient_fields:

Show one input for each entry in recipient_fields.
Use the entry’s label as the input’s label.
Send the value in recipient, under the entry’s key.

For example, these recipient_fields:

"recipient_fields": [
  { "key": "player_id", "label": "Player ID", "required": true },
  { "key": "zone_id", "label": "Zone ID", "required": true }
]

become this recipient in your order:

"recipient": { "player_id": "12345678", "zone_id": "1234" }

Try it with the sandbox catalog. Switch to العربية (Arabic) to see the labels the API returns for Accept-Language: ar. The form is then laid out right to left:

Recipient form builderBuilt from the sandbox catalog

Product

What your customer sees

POST /api/b2b/v1/orders body

Rules the API enforces

Send every key in recipient_fields. If a key is missing, you get 422 validation_failed. This happens before any order or fulfillment exists. details says what is missing, for example "recipient": ["is missing zone_id"].
Send values as strings. Player IDs can start with zero. "00123456789" and 123456789 are different accounts.
Use the exact key from recipient_fields. NEVER use another name for the same field. Send player_id, not userId or account_id, unless that exact key is in recipient_fields.
Vouchers take delivery contacts only. For voucher products, recipient may hold name, email, and mobile. If you send a top-up field such as player_id, you get 422 with topup recipient fields are not accepted for voucher products.
Top-ups take recipient_fields keys only. If you send name, email, mobile, or any other key that the top-up doesn’t list, you get 422 with "recipient": ["contains unexpected fields: email"]. If recipient isn’t a JSON object, you get "recipient": ["must be an object"].

Cardzone delivers voucher codes too

When a voucher order is fulfilled, Cardzone sends the code to the contacts in recipient:

by email to email.
by SMS to mobile, and also by WhatsApp where it is enabled.

The codes are also in codes[] on the order.

If you deliver codes yourself, leave out email and mobile. Otherwise your customer gets the code twice.

When an order has an email or mobile, Cardzone also creates or updates a customer record in your Cardzone store.

Filter by category

List categories returns category slugs (short text IDs) such as pubg. To show only one category, pass its slug as category_id to List products. An unknown slug returns 404.

Availability

Every product and category has a status:

`status`	Meaning
`available`	Your store can order it now.
`out_of_stock`	Sold out for now. It usually comes back. Keep it in your catalog and show it as sold out.
`unavailable`	Your store can’t order it right now, for any other reason.

By default, List products and List categories return only what you can order now. So every row is available.

Add include_unavailable=true to also get products that you can see but can’t order right now. They are marked out_of_stock or unavailable. Then you can show “sold out” instead of hiding the product with no explanation.

A category’s status is the best status among its products.

Some products never appear, even with include_unavailable: products that are hidden from your store, and products that have no price.

Availability can change between the time you list products and the time you order. If you order a product you can’t order, you get 404 with details: "product_not_found". When Cardzone knows why, error.product_status tells you:

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed",
    "details": "product_not_found",
    "product_status": "out_of_stock"
  }
}

What to do:

out_of_stock: try again later.
unavailable, or no product_status at all (the product is unknown or deleted): refresh your saved copy of the catalog.

In every case, refresh your saved copy of the catalog regularly.