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

# Security Overview: Protecting Your Wasl Integration

> Learn how Wasl secures your API integration through token-based authentication, IP whitelisting, and strict data integrity controls.

Wasl protects your integration and your customers' gift card data through a layered security model. Every API request you make is authenticated with a Bearer token, tied to a registered IP address, and processed in an environment that enforces strict data integrity rules. Understanding these principles helps you build a secure, reliable integration and respond quickly if anything looks out of place.

## Security Principles

Wasl's API is built around four core security principles. Each one defines a specific boundary that keeps your account and card data safe.

<AccordionGroup>
  <Accordion title="Accessibility — Authorized Access Only">
    Only authenticated users can log in to the Payzah system and call API services. You must obtain a valid Bearer token before making any request, and every subsequent call must include that token in the `Authorization` header.

    <Note>
      If your token expires or becomes invalid, all API calls will be rejected until you re-authenticate via `POST /api-service/card/login`.
    </Note>
  </Accordion>

  <Accordion title="Confidentiality — Your Data Stays Private">
    Only authorized Payzah users can access data through the API. Your card inventory, transaction history, and account details are never exposed to other merchants.

    If a card or voucher cannot be redeemed, Payzah provides a card replacement interface that lets you swap it for a replacement card carrying the same value — without any loss of balance for you or your customers.
  </Accordion>

  <Accordion title="Integrity — Immutable Card Codes">
    All card data is maintained in a correct and trusted state and is provided exclusively by Payzah. No party — including merchants — can modify card codes once they have been issued. Payzah can add new card stock and replenish existing inventory, but the underlying card codes themselves are immutable.

    <Info>
      This design ensures that every card code your customer receives is exactly as Payzah generated it — untampered and valid for redemption.
    </Info>
  </Accordion>

  <Accordion title="Availability — Controlled Interface Access">
    Access to the card replacement interface and the Issued Cards page is restricted to authorized users who have been explicitly granted that permission. Even within your own organization, only users with the correct role can view issued cards or initiate replacements.
  </Accordion>
</AccordionGroup>

***

## Token-Based Authentication

Wasl uses Bearer token authentication for every API request. Tokens are short-lived credentials that prove your identity to the API without transmitting your password on every call.

### How to Obtain a Token

Send a `POST` request to the login endpoint with your credentials:

```http theme={null}
POST /api-service/card/login
Content-Type: application/json

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

A successful response returns an access token. Include it in the `Authorization` header of every subsequent request:

```http theme={null}
Authorization: Bearer <your_token>
```

### Keeping Your Credentials Safe

Follow these practices to protect your token and private key:

* **Never share your private key.** You receive a private key when you register with Wasl. Treat it like a password — store it in an environment variable or a secrets manager, never in source code or version control.
* **Rotate immediately if compromised.** If you suspect your token or private key has been exposed, contact Wasl support to invalidate the old key and issue a new one.
* **Do not log tokens.** Avoid writing your Bearer token to application logs, which may be stored or transmitted insecurely.
* **Use HTTPS at all times.** All API calls must be made over HTTPS. Never send credentials over plain HTTP.

<Warning>
  If your private key is ever committed to a public repository or shared externally, treat it as compromised and request a replacement from Wasl support immediately.
</Warning>

***

## IP Whitelisting

Wasl ties API access to a registered IP address. Only requests originating from your registered IP will be accepted — all others are rejected before any authentication check is performed.

### Registering Your IP Address

Provide your server's public IP address to Wasl during the onboarding process. Once registered, that IP is linked to your merchant account.

<Tip>
  If your integration runs on a cloud provider, make sure you are using a static or Elastic IP address. Dynamic IPs change on restart and will break your API access without warning.
</Tip>

### Updating Your IP Address

If your server IP changes — for example, after a cloud migration, a server rebuild, or a network reconfiguration — you must update your registered IP with Wasl before making new API calls. Contact Wasl support to update your whitelisted address.

<Note>
  Until your new IP is registered, all API calls from the new address will be rejected with an authentication error, even if your token is valid.
</Note>

***

## Requesting Access to Additional Card Types

Your account is configured with a specific set of card types and vendors at the time of onboarding. If you need to sell card types that do not currently appear in your card list, contact Wasl to request access to additional inventory.

Wasl will review your request and, if approved, add the new card types to your account. The new options will then appear when you query your available card catalog.

<Info>
  You can view your currently available card types at any time by calling the card list endpoint. Any card type not returned by that endpoint is not yet enabled for your account.
</Info>

***

## Environments

Use the appropriate base URL depending on your current development stage:

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

<Warning>
  Never use production credentials in the development environment, and never point a live customer-facing application at the development URL.
</Warning>


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