> ## 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: End-to-End Integration Request Flow

> Walk through the complete Wasl Cards API sequence — from authentication and catalog caching to order placement and delivering card codes to customers.

Every successful card sale follows a fixed sequence of API calls. Understanding this flow before you write a single line of code saves you from unnecessary round-trips, avoids common errors, and ensures your customers receive their card codes as quickly as possible. Work through each step below to build a clear mental model of how all the pieces fit together.

<Note>
  You must pass your session token as an `Authorization` header on **every** API call after authentication. Any request that omits this header will return error code `10000` (Incorrect Token Access). Store the token securely and attach it automatically to all outbound requests.
</Note>

## Integration sequence

<Steps>
  <Step title="Register your merchant account">
    Before making any API calls, contact Wasl to provision your merchant credentials (username and password). You will use these credentials to authenticate against the API and receive a session token.

    You have access to two environments:

    | Environment | Base URL |
    | - | - |
    | Development | `https://development.payzah.net/` |
    | Production | `https://payzah.net/production770/` |

    Always build and test against the **development** environment before pointing your integration at production.
  </Step>

  <Step title="Authenticate and retrieve your session token">
    Call the authentication endpoint with your username and password. A successful response returns a unique session token. Store this token — you need it for every subsequent request.

    ```bash Request theme={null}
    POST https://development.payzah.net/api-service/card/login
    ```

    ```json Response theme={null}
    {
      "status": true,
      "code": "11111",
      "token": "unique token"
    }
    ```

    <Tip>
      Re-authenticate whenever your token becomes invalid (error code `10000`). Build a token-refresh mechanism into your HTTP client so that retries are handled automatically without interrupting the user experience.
    </Tip>
  </Step>

  <Step title="Fetch and cache the card catalog">
    Call **Get Card List** and **Get Card Details** once during your initial setup. Persist the results in your own database so that your storefront can display card names, denominations, and pricing without hitting the Wasl API on every page load.

    <Note>
      Wasl card catalog changes infrequently. Cache the full catalog on your first run and schedule a periodic refresh (for example, once every 24 hours) rather than fetching it on every customer request. This keeps your integration fast and reduces unnecessary API traffic.
    </Note>

    The catalog data includes both English (`name` / `name_in_english`) and Arabic (`name_ar` / `name_in_arabic`) display names, so you can serve multilingual storefronts from a single dataset.
  </Step>

  <Step title="Customer selects a card — check available balance">
    When a customer chooses a card denomination and quantity, call **Get Card Balance** before proceeding. This tells you how many units Wasl currently has in stock for that `card_id`.

    ```bash Request theme={null}
    POST https://development.payzah.net/api-service/card/get-balance-details
    ```

    If the returned `balance` is lower than the quantity your customer wants, surface an out-of-stock message rather than letting the order fail later with error `10006` (Insufficient Balance).
  </Step>

  <Step title="Initiate the card request">
    Once you have confirmed sufficient stock, call **Initiate Card Request** with the `card_id`, desired quantity (`quantiry` — use this exact spelling as it appears in the API), and your own `transaction_number`. The API responds with a `transaction_id` that ties together the reservation.

    ```bash Request theme={null}
    POST https://development.payzah.net/api-service/card/initiate-card-request
    ```

    <Warning>
      Persist the `transaction_id` returned from this step immediately. You cannot confirm the order or retrieve card codes without it, and you will need it again if you ever need to raise a support request with Wasl.
    </Warning>
  </Step>

  <Step title="Confirm the order and receive card codes">
    After collecting payment from your customer, call **Confirm Order** with the `transaction_id`, the `total_amount`, and your internal `payment_id`. A successful response returns an array of `card_code` and `card_number` pairs — one entry per card unit purchased.

    ```bash Request theme={null}
    POST https://development.payzah.net/api-service/card/confirm-order
    ```

    ```json Response theme={null}
    {
      "status": true,
      "code": "11111",
      "data": [
        { "card_code": "QWERTY123", "card_number": "123456789" },
        { "card_code": "QWERTY123", "card_number": "123456789" }
      ]
    }
    ```
  </Step>

  <Step title="Deliver card codes to the customer">
    Display or email the `card_code` and `card_number` values to the customer. Store the complete order record (transaction ID, card codes, card numbers, timestamp) in your system.

    If a customer reports a faulty card, you can use the **Cards Console Panel** to replace it by entering the original transaction number — Payzah will generate a fresh card for the end user. See the [Console Panel](/guides/console-panel) guide for details.
  </Step>
</Steps>

## Error code reference

Use the table below as a quick reference when diagnosing failed responses.

| Code | Description |
| - | - |
| 10000 | Incorrect Token Access |
| 10001 | Error while Processing the request |
| 10002 | No Card Data Found |
| 10003 | Improper Way for Calling API - Method |
| 10005 | Card ID Missing |
| 10006 | Insufficient Balance |
| 10007 | Username missing |
| 10008 | Password missing |

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    Learn how to obtain and manage your session token.
  </Card>

  <Card title="Card Catalog" icon="layer-group" href="/guides/card-catalog">
    Fetch and cache the full card catalog for your storefront.
  </Card>

  <Card title="Placing Orders" icon="cart-shopping" href="/guides/placing-orders">
    Step-by-step guide to checking balance, initiating, and confirming orders.
  </Card>

  <Card title="Console Panel" icon="gauge" href="/guides/console-panel">
    Replace faulty cards and view sales reports in the merchant dashboard.
  </Card>
</CardGroup>


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