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

# Wasl Cards API Authentication and Session Tokens

> Learn how to obtain a session token, attach it to every API request, handle token expiry, and resolve authentication errors with the Wasl Cards API.

Every request to the Wasl Cards API must be authenticated. You prove your identity once by exchanging your merchant credentials for a session token, and then you attach that token to every subsequent call. This page walks you through the login endpoint, shows you exactly how to pass the token, and explains what to do when authentication fails.

<Warning>
  Never share your password or your active session token in client-side code, public repositories, or log files. Treat the token like a password — if you believe it has been compromised, re-authenticate immediately to obtain a new one.
</Warning>

## Obtain a session token

Send a `POST` request to the login endpoint with your merchant credentials in the request body.

**Endpoint**

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

<CodeGroup>
  ```json Request body theme={null}
  {
    "user_name": "your_username",
    "password": "your_password"
  }
  ```

  ```bash cURL example theme={null}
  curl --request POST \
    --url https://development.payzah.net/api-service/card/login \
    --header 'Content-Type: application/json' \
    --header 'Token: token' \
    --data '{
      "user_name": "your_username",
      "password": "your_password"
    }'
  ```
</CodeGroup>

### Required headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `Token` | `token` |

### Request body fields

| Field | Type | Required | Description |
| - | - | - | - |
| `user_name` | string | ✅ | Your Wasl merchant username. |
| `password` | string | ✅ | Your Wasl merchant password. |

### Successful response

A `200 OK` response contains a `token` field. This is your session token.

```json Response theme={null}
{
  "status": true,
  "code": "11111",
  "token": "unique token"
}
```

Store this token value securely — in an environment variable or a secrets manager — so that your application can attach it to outbound requests without hardcoding it in source code.

## Attach the token to subsequent requests

After you obtain the token, pass it as the `Authorization` header on **every** API call you make.

### Required headers for authenticated requests

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `Authorization` | The token from the login response |
| `Token` | `token` |

```bash Authenticated request example theme={null}
curl --request GET \
  --url https://development.payzah.net/api-service/card/get-card-list \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_session_token' \
  --header 'Token: token'
```

<Note>
  Both the `Authorization` header (your dynamic session token) and the static `Token: token` header are required on authenticated endpoints. Omitting either one will result in an authentication error.
</Note>

## Token lifecycle and re-authentication

Your session token is valid for a fixed period. When the token expires, any API call will return error code `10000` (Incorrect Token Access). At that point, repeat the login request with your credentials to obtain a fresh token and resume normal operations.

<Tip>
  Build automatic token refresh into your HTTP client. Intercept responses that carry error code `10000`, silently re-authenticate, and retry the original request. This prevents transient token expiry from surfacing as errors to your end users.
</Tip>

## Handling authentication errors

### Error 10000 — Incorrect Token Access

This error means the token you sent is missing, malformed, or has expired.

**How to resolve it:**

1. Confirm you are including the `Authorization` header on the request.
2. Check that you are copying the full token value without truncation or extra whitespace.
3. Re-authenticate by calling the login endpoint to obtain a new token.
4. Retry the failed request with the fresh token.

### Error 10007 — Username missing

You called the login endpoint without a `user_name` field in the request body. Add the field and retry.

### Error 10008 — Password missing

You called the login endpoint without a `password` field in the request body. Add the field and retry.

## Environments

Use the correct base URL for each stage of development.

| Environment | Base URL |
| - | - |
| Development | `https://development.payzah.net/` |
| Production | `https://payzah.net/production770/` |

<Warning>
  The login endpoint and all other endpoints differ by base URL only — the path segments remain the same. Make sure your environment configuration controls the base URL so you never accidentally hit production during testing.
</Warning>


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