Placing Gift Card Orders with the Wasl Cards API

Check available stock, initiate a card reservation, and confirm payment to receive card codes — a full order walkthrough for Wasl Cards API merchants.

Placing a card order is a three-step process: you verify that enough stock is available, reserve the cards against a transaction, and then confirm payment to unlock the card codes. Splitting the flow this way lets you check inventory before charging the customer and gives you a clear transaction record at every stage. Follow the steps below in order — skipping any one of them will result in an error.

Always check the available balance for a card_id before initiating an order. If you proceed without enough stock, the API will return error code 10006 (Insufficient Balance) and your order will fail without generating card codes.

Step 1 — Check available balance

Before you initiate any order, confirm that Wasl holds enough units of the card your customer wants.

Endpoint

POST https://development.payzah.net/api-service/card/get-balance-details

Required headers

Header	Value
Content-Type	application/json
Authorization	Your session token from login
Token	token

Request body

{
  "card_id": 59
}

Request body fields

Field	Type	Required	Description
card_id	integer	✅	The denomination ID from the Get Card Details response.

Response

Response

{
  "status": true,
  "code": "11111",
  "data": [
    {
      "card_id": 59,
      "balance": 5
    }
  ]
}

If balance is less than the quantity your customer wants to purchase, show an out-of-stock message and do not proceed to the initiate step.

---

Step 2 — Initiate the card request

Once you have confirmed sufficient stock, reserve the cards by calling the Initiate Card Request endpoint. This creates a pending transaction and returns a transaction_id that you must use in the confirm step.

Endpoint

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

Required headers

Header	Value
Content-Type	application/json
Authorization	Your session token from login
Token	token

Request body fields

Field	Type	Required	Description
card_id	integer	✅	The denomination ID for the card the customer is purchasing.
quantiry	integer	✅	The number of card units to reserve. Note: this field name contains a typo in the API — pass it exactly as quantiry (not quantity).
transaction_number	integer	✅	Your own internal transaction reference number.

Request body

{
  "card_id": 59,
  "quantiry": 2,
  "transaction_number": 100042
}

The quantiry field name is spelled this way in the Wasl API itself. You must pass the key exactly as quantiry — using the correct spelling (quantity) will cause the request to fail silently or be ignored.

Save the transaction_id returned in this response to durable storage immediately. You cannot confirm the order, retrieve card codes, or raise a support request without it. If your process crashes between the initiate and confirm steps, the transaction ID is your only recovery handle.

---

Step 3 — Confirm the order and receive card codes

After you have collected payment from your customer, call the Confirm Order endpoint to finalize the transaction. Wasl will verify the amount and release the card codes.

Endpoint

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

Required headers

Header	Value
Content-Type	application/json
Authorization	Your session token from login
Token	token

Request body fields

Field	Type	Required	Description
transaction_id	string	✅	The transaction ID returned by the Initiate Card Request call.
total_amount	float	✅	The total amount charged for this order (unit price × quantity).
payment_id	string	✅	Your internal payment reference (for example, a payment gateway confirmation ID).

Request body

{
  "transaction_id": "244101585669013",
  "total_amount": 6.6,
  "payment_id": "12345672312"
}

Response

A successful response returns an array of card objects — one per unit ordered. Each object contains a card_code and a card_number to deliver to the customer.

Response

{
  "status": true,
  "code": "11111",
  "data": [
    {
      "card_code": "QWERTY123",
      "card_number": "123456789"
    },
    {
      "card_code": "QWERTY123",
      "card_number": "123456789"
    }
  ]
}

Response fields

Field	Type	Description
card_code	string	The redemption code the customer enters to activate the card.
card_number	string	The card’s unique serial number.

Deliver the card_code and card_number to your customer and persist the complete order record in your system.

---

Error code reference

Code	Description	Resolution
10000	Incorrect Token Access	Re-authenticate and retry with a fresh session token.
10005	Card ID Missing	Include the card_id field in your request body.
10006	Insufficient Balance	Check stock with Get Balance Details before initiating future orders.
10001	Error Processing Request	Verify all request fields and retry; contact Wasl support if it persists.