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

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

<Warning>
  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.
</Warning>

## 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` |

<CodeGroup>
  ```json Request body theme={null}
  {
    "card_id": 59
  }
  ```

  ```bash cURL example theme={null}
  curl --request POST \
    --url https://development.payzah.net/api-service/card/get-balance-details \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_session_token' \
    --header 'Token: token' \
    --data '{ "card_id": 59 }'
  ```
</CodeGroup>

### Request body fields

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

### Response

```json Response theme={null}
{
  "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. |

<CodeGroup>
  ```json Request body theme={null}
  {
    "card_id": 59,
    "quantiry": 2,
    "transaction_number": 100042
  }
  ```

  ```bash cURL example theme={null}
  curl --request POST \
    --url https://development.payzah.net/api-service/card/initiate-card-request \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_session_token' \
    --header 'Token: token' \
    --data '{
      "card_id": 59,
      "quantiry": 2,
      "transaction_number": 100042
    }'
  ```
</CodeGroup>

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

***

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

<CodeGroup>
  ```json Request body theme={null}
  {
    "transaction_id": "244101585669013",
    "total_amount": 6.6,
    "payment_id": "12345672312"
  }
  ```

  ```bash cURL example theme={null}
  curl --request POST \
    --url https://development.payzah.net/api-service/card/confirm-order \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_session_token' \
    --header 'Token: token' \
    --data '{
      "transaction_id": "244101585669013",
      "total_amount": 6.6,
      "payment_id": "12345672312"
    }'
  ```
</CodeGroup>

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

```json Response theme={null}
{
  "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. |


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