Skip to main content
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.
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.

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

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

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

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

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

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

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

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