Wasl Cards API: Getting Started with Integration

Register your merchant account, obtain your private key and credentials, and make your first authenticated request to the Wasl Cards API in minutes.

Getting up and running with the Wasl Cards API takes four steps: register your merchant account, receive your credentials, call the Authentication API to obtain a session token, and then use that token to access every other endpoint. Follow the steps below to complete your initial setup.

1. Register Your Merchant Account

   Send a registration email to Wasl with the following information. Fields marked required must be included or your registration cannot be processed.

   #	Field	Required
   1	Username in English	✅ Required
   2	Username in Arabic	✅ Required
   3	Address in English	Optional
   4	Address in Arabic	Optional
   5	Mobile Number	✅ Required
   6	Alternative Number	Optional
   7	Email Address	✅ Required
   8	Website URL	Optional
   9	Company Name	Optional
   10	Company Short Description	Optional
   11	IP Address	✅ Required

   Providing your IP address is mandatory. Wasl uses it to restrict API access to known, authorised sources. If your server IP changes after registration, contact Wasl to update it before making API calls.

2. Receive Your Credentials

   After Wasl processes your registration, you will receive a private key by email. This key acts as your password when authenticating with the API.

   Keep your private key confidential. Do not share it, commit it to source control, or expose it in client-side code. If your private key is compromised, contact Wasl immediately to have it rotated.

   You will use your credentials against one of the two environments depending on where you are in the development cycle:

   Environment	Base URL
   Development	https://development.Payzah.net/
   Production	https://Payzah.net/production770/

   Start all development and testing against the Development environment. Only switch to Production once your integration is complete and validated end-to-end.

3. Make Your First API Call — Authenticate

   Call the login endpoint to exchange your username and private key for a session token. This is always the first call you make in any session.

   Endpoint

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

   Request headers

   Content-Type: application/json
   Token: token
   

   Request body

   {
     "user_name": "your_username",
     "password": "your_password"
   }
   

   Successful response — HTTP 200

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

   When status is true, the token field contains your session token. Store this value — you will pass it in the Token header of every subsequent API request.

   If authentication fails, check that you are sending the correct user_name and password values. Error code 10007 indicates a missing username and 10008 indicates a missing password. See the Error Codes reference for the full list.

4. Use the Token in Subsequent Requests

   Every API endpoint beyond login requires the session token you received in Step 3. Pass it as the value of the Token request header on each call.

   Content-Type: application/json
   Token: <your_session_token>
   

   If you supply an invalid or expired token, the API returns error code 10000 (Incorrect Token Access). When this happens, re-authenticate by calling the login endpoint again to obtain a fresh token.

   Build token refresh logic into your integration from the start. A clean pattern is to catch 10000 errors centrally, re-authenticate, then retry the original request automatically.

What’s Next?

With authentication in place, you are ready to load the card catalog and start building your storefront flow.

Core Concepts

Understand vendors, cards, balances, transactions, and tokens before making your next API call.

Request Flow Guide

Follow the complete end-to-end flow from catalog retrieval through order confirmation with full code examples.