> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.epaygames.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.epaygames.io/_mcp/server.

# Authentication

Both the Payments API and the Disbursement API use **Bearer token authentication**. Each API has its own token endpoint, its own token, and its own environment variable — a Payments API token cannot be used against the Disbursement API, and vice versa.

## Payments API — Create Token

**`POST`** `/v1/biller/token/create`

Generates the bearer token used to authenticate every other Payments API request.

* Credentials (`username`, `password`) are passed as **query parameters**, not a JSON body.
* Requires a header `X-Server: 1`.
* Returns a token valid for **up to 60 minutes** (`expires_in: 3600` seconds).

```text title="Example request"
POST https://{{payments_api_host}}/v1/biller/token/create?username=test-merchant&password=p@ssw0rd01
X-Server: 1
```

```json title="Example response"
{
    "message": "Successfully authenticated.",
    "data": {
        "token": "yDElUGArkNE5ZHc23ghadZNEOcCcPuSDY1LbVGTO08c2770a",
        "type": "Bearer",
        "expires_in": 3600
    }
}
```

### Usage Guidelines

Call this no more than once every 55 minutes — reuse the token rather than re-authenticating on every request.

* **Store the token securely.** An in-memory cache is recommended; encrypted local storage or your system's secure key store are acceptable alternatives.
* `expires_in` is in **seconds** — `3600` means 60 minutes.
* Send the token on every subsequent request as:
  ```text
  Authorization: Bearer <your_token_here>
  ```
* A `Signature Key` is also issued alongside your sandbox credentials (`9XAgVZzU4WhqrXA6jEvMtkF85j8wKZZhQ5RE2hsDPwa5rjPT7RpCmJceu8jNt4Wy`) as part of your merchant credential set.

## Disbursement API — Create Access Token

**`POST`** `/v1/auth/token`

Generates the bearer token used to authenticate every other Disbursement API request.

* Credentials are passed as a **JSON body**, not query parameters.
* Returns a token valid for approximately **60 minutes** (`expires_in` \~3600 seconds).

```json title="Example request"
POST https://{{disbursement_api_host}}/v1/auth/token
Content-Type: application/json

{
    "username": "test-merchant",
    "password": "p@ssw0rd01"
}
```

```json title="Example response"
{
    "message": "Authenticated.",
    "data": {
        "token": "XPy8qeGESyyZanHNCyvKkNAPp2uc14lcjyGytI5g1eRunClHUeco2GKCuCgsNX3043cyBUCMUrEB2vkAaF2L6879mmd8PxO3vBZi2hLQNCz3Hd4E8Eeul6uTj04CZmK5",
        "type": "Bearer",
        "expires_in": 3601
    }
}
```

### Usage Guidelines

* Must be called **before** any other Disbursement API request.
* On success, the token is **automatically saved** to the `token` environment variable, so it's immediately available to every other request in the collection — no manual copy/paste needed.
* Use your assigned sandbox/staging test credentials while integrating.

## Sending the Token

Regardless of which API you're calling, authenticated requests all use the same header format:

```text
Authorization: Bearer <token>
```

## Quick Comparison

|                              | Payments API                   | Disbursement API                    |
| ---------------------------- | ------------------------------ | ----------------------------------- |
| Endpoint                     | `POST /v1/biller/token/create` | `POST /v1/auth/token`               |
| Credential location          | Query parameters               | JSON body                           |
| Extra header required        | `X-Server: 1`                  | —                                   |
| Token lifetime               | \~3600 seconds (60 min)        | \~3600–3601 seconds (60 min)        |
| Auto-saved variable          | `payments_api_token`           | `token`                             |
| Recommended re-auth interval | Every 55 minutes               | Reuse for the token's full lifetime |