# Pay Sessions API

Create the pay tokens that authorize a hosted payment flow. Token validation is performed by the hosted Elements page, not by your server.

> **Scope of this file.** It is the OPERATION reference for THIS resource, generated from the BillerAPI OpenAPI document served at [/docs/openapi.json](/docs/openapi.json): each API-key endpoint the resource owns, with its parameters, request body, responses and schemas. Narrative and catalog sections the rendered page also carries (walkthroughs, event taxonomies, payload catalogs) are NOT reproduced here — read [/docs/api/pay-sessions](/docs/api/pay-sessions) for those. Endpoints the hosted flow drives from inside the iframe, and dashboard-session endpoints, are absent by design: they are not API-key operations. [/docs/api.md](/docs/api.md) enumerates the full API-key surface, including the endpoints that have no reference page yet.

All request and response field names are snake_case. Errors use the coded envelope described in [/docs/concepts/errors.md](/docs/concepts/errors.md).

## Endpoints

- [`POST /v1/pay-tokens`](#post-v1pay-tokens)

## POST /v1/pay-tokens

Create pay token

Mint a pay_token for the hosted Elements add-payment-method / pay flows. Server-to-server: requires client credentials. Short-lived (15 min).

Operation ID: `createPayToken`

Auth: `client-api-key`

**Request body** (required)

Schema: `CreatePayTokenDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `client_user_id` | yes | string | — | Your identifier for the end user this token is scoped to. |
| `bill_id` | no | string | — | Bill this token authorizes paying. |
| `amount` | no | PayTokenAmountDto | — | Amount scope (minor units + ISO 4217 currency). |
| `payment_method_id` | no | string | — | Pre-selected payment method to scope the token to. |
| `client_id` | no | string | — | Explicit client id. Validated against the credential; 403 on mismatch. |
| `metadata_json` | no | string | — | Opaque JSON metadata string echoed back on the token. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | Pay token created successfully | — |
| 400 | Invalid request | — |
| 401 | Missing or invalid client credentials | — |
| 403 | Body client_id does not match the authenticated client | — |

## Schemas

### CreatePayTokenDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `client_user_id` | yes | string | — | Your identifier for the end user this token is scoped to. |
| `bill_id` | no | string | — | Bill this token authorizes paying. |
| `amount` | no | PayTokenAmountDto | — | Amount scope (minor units + ISO 4217 currency). |
| `payment_method_id` | no | string | — | Pre-selected payment method to scope the token to. |
| `client_id` | no | string | — | Explicit client id. Validated against the credential; 403 on mismatch. |
| `metadata_json` | no | string | — | Opaque JSON metadata string echoed back on the token. |

### PayTokenAmountDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `value` | yes | number | — | Amount in minor units. |
| `currency` | yes | string | — | ISO 4217 currency code. |


## See also

- [API reference index](/docs/api.md)
- [Authentication](/docs/guides/authentication.md)
- [Pagination](/docs/concepts/pagination.md)
- [Error handling](/docs/concepts/errors.md)