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.

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.

Integration sequence

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

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

   Request

   POST https://development.payzah.net/api-service/card/login
   

   Response

   {
     "status": true,
     "code": "11111",
     "token": "unique token"
   }
   

   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.

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

   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.

   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.

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

   Request

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

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

   Request

   POST https://development.payzah.net/api-service/card/initiate-card-request
   

   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.

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

   Request

   POST https://development.payzah.net/api-service/card/confirm-order
   

   Response

   {
     "status": true,
     "code": "11111",
     "data": [
       { "card_code": "QWERTY123", "card_number": "123456789" },
       { "card_code": "QWERTY123", "card_number": "123456789" }
     ]
   }
   
7. 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 guide for details.

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

Authentication

Learn how to obtain and manage your session token.

Card Catalog

Fetch and cache the full card catalog for your storefront.

Placing Orders

Step-by-step guide to checking balance, initiating, and confirming orders.

Console Panel

Replace faulty cards and view sales reports in the merchant dashboard.