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

<Steps>
  <Step title="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 |

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

  <Step title="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.

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

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

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

  <Step title="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**

    ```http theme={null}
    Content-Type: application/json
    Token: token
    ```

    **Request body**

    ```json theme={null}
    {
      "user_name": "your_username",
      "password": "your_password"
    }
    ```

    **Successful response — HTTP 200**

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

    <Note>
      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](/concepts#error-codes) reference for the full list.
    </Note>
  </Step>

  <Step title="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.

    ```http theme={null}
    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.

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>

## What's Next?

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

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book-open" href="/concepts">
    Understand vendors, cards, balances, transactions, and tokens before making your next API call.
  </Card>

  <Card title="Request Flow Guide" icon="diagram-project" href="/guides/request-flow">
    Follow the complete end-to-end flow from catalog retrieval through order confirmation with full code examples.
  </Card>
</CardGroup>


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