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

# Wasl Cards API: Core Concepts and Key Terminology

> Understand the key building blocks of the Wasl Cards API — vendors, cards, balances, transactions, tokens, and the two integration environments.

Before you dive into API calls, it helps to have a clear mental model of how Wasl structures its data and what each term means. This page defines every core concept you will encounter across the Wasl Cards API documentation and within API responses themselves.

## Vendor

A **vendor** is a card brand or content provider available on the Wasl platform — for example, Xbox, PlayStation, or a retail gift card issuer. Each vendor is identified by a unique `vendor_id` and may offer multiple card denominations under their brand.

When you call the Get Card List endpoint, the response groups cards by vendor. You typically cache vendor data locally and use it to populate brand-level navigation in your storefront.

<Note>
  Card names are returned in both English and Arabic to support multilingual storefronts. The English name is provided in the `name` field and the Arabic name in the `name_ar` field. Display the appropriate version based on your customer's locale.
</Note>

## Card

A **card** is a specific denomination offered by a vendor — for example, an "Xbox \$10" top-up card. Each card is identified by a unique `card_id` and carries two key numeric properties:

* **`amount`** — the face value of the card (e.g., 10.00)
* **`balance`** — the quantity of that card type currently available in Wasl inventory (see [Balance](#balance) below)

You retrieve cards by calling Get Card List (for all accessible cards) or Get Card Details (for the cards belonging to a specific vendor). Cache this data in your system to avoid unnecessary API calls on every page load.

<Tip>
  Refresh your cached card catalog periodically — for example, once per day — to capture any new denominations or vendors Wasl has made available to your account.
</Tip>

## Balance

**Balance** refers to the available stock quantity of a particular card type held by Wasl at any given moment. Before presenting a card to a customer or placing an order, call the Get Balance Details endpoint with the relevant `card_id` to confirm that sufficient stock exists.

<Warning>
  Do not rely on a cached balance value. Always call Get Balance Details at the point of purchase. If you attempt to order a card with insufficient stock, the API returns error code `10006` (`Insufficient Balance`) and the order will not be created.
</Warning>

## Transaction

A **transaction** represents a card order request. When you call the Initiate Card Request endpoint, Wasl creates a transaction and returns two identifiers:

* **`transaction_id`** — used when calling the Confirm Order endpoint to complete the purchase
* **`transaction_number`** — the human-readable reference used in the Cards Console Panel (for example, when requesting a card replacement)

Store both identifiers against your internal order record. The transaction is not fulfilled until you call Confirm Order, at which point Wasl returns the redeemable card codes.

<Note>
  A transaction has a two-stage lifecycle: **initiated** (order placed, codes not yet issued) and **confirmed** (codes issued and ready to deliver). Always complete the confirm step — an initiated-but-unconfirmed transaction does not deliver card codes to the customer.
</Note>

## Token

A **token** is a session credential returned by the Authentication API (`POST /api-service/card/login`). Every request to every other endpoint must include the token in the `Token` HTTP header. Without a valid token, the API returns error code `10000` (`Incorrect Token Access`).

Tokens are scoped to your merchant account and tied to the IP address registered with Wasl. If your token expires or becomes invalid, re-authenticate by calling the login endpoint again.

<Warning>
  Never expose your token in client-side code, browser storage, or public logs. Treat it with the same care as a password. If you suspect your token has been compromised, re-authenticate immediately to invalidate the old one and obtain a fresh token.
</Warning>

## Webhook

A **webhook** is an HTTP POST callback that Wasl sends to a URL you provide whenever a notable event occurs — such as an order status update or a platform system event. Your endpoint must respond with an HTTP `200` status to acknowledge receipt.

<Note>
  Webhooks allow your system to react to events asynchronously rather than polling the API. Configure your webhook endpoint to be publicly accessible and protected against unauthorised requests.
</Note>

## Cards Console Panel

The **Cards Console Panel** is the Wasl-hosted merchant dashboard. It provides two key capabilities:

* **Card Replacement** — if a customer receives a card code that cannot be redeemed, enter the associated transaction number in the Console to generate a replacement card automatically.
* **Sales Reporting** — view a summary of your total sales volume and transaction amounts across all card types.

<Info>
  The Cards Console Panel is separate from the API itself. You access it via the Wasl merchant portal using your registered credentials. Use it as an operational tool for support and reconciliation, not as a substitute for the API in your integration.
</Info>

## Environments

Wasl provides two completely isolated environments. Use Development while building and testing your integration, and switch to Production only when you are ready to go live.

| Environment | Base URL | Purpose |
| - | - | - |
| **Development** | `https://development.Payzah.net/` | Integration development and testing |
| **Production** | `https://Payzah.net/production770/` | Live merchant transactions |

<Warning>
  Requests made against the Production environment are real. They consume live card inventory and generate actual transactions. Never use Production credentials or the Production base URL during development or testing.
</Warning>

## Error Codes Reference

When an API call fails, Wasl returns a JSON response containing a numeric error code. Use the table below to diagnose and handle errors in your integration.

| Code | Description | Common Cause |
| - | - | - |
| `10000` | Incorrect Token Access | Missing, expired, or invalid `Token` header |
| `10001` | Error while Processing the request | Unexpected server-side error; retry the request |
| `10002` | No Card Data Found | The requested card ID does not exist or is inaccessible |
| `10003` | Improper Way for Calling API — Method | Wrong HTTP method used for the endpoint |
| `10005` | Card ID Missing | The `card_id` field was not included in the request body |
| `10006` | Insufficient Balance | Wasl does not have enough stock to fulfil the order quantity |
| `10007` | Username Missing | The `user_name` field was not included in the login request |
| `10008` | Password Missing | The `password` field was not included in the login request |

<Note>
  For error `10001`, implement retry logic with exponential back-off. For error `10006`, call Get Balance Details before retrying so you can present accurate stock information to your customer.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.