> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payor APIs

> Checkout/session endpoints for customer-facing payment flows.

## Overview

Payor APIs are used by the checkout experience to display available tokens, create payment addresses, and poll payment status. These endpoints are safe for browser or mobile clients because they use short-lived session headers generated when you create an invoice.

## Authentication

Payor requests use session headers returned when you create an invoice:

* `x-session-token: pst_...`
* `x-signature: sig_...`

Do not send merchant or commerce API keys in client-side code.

## Request

```bash theme={null}
curl "https://api-beta.pepay.io/api/v1/payments/session-details?invoice_id=<invoice_id>" \
  -H "x-session-token: pst_..." \
  -H "x-signature: sig_..."
```

## Response

```json theme={null}
{
  "status": "ok",
  "data": {
    "invoice_id": "inv_123",
    "environment": "devnet"
  }
}
```

## Errors

* `401` missing/invalid payor session headers
* `403` signature/session mismatch
* `404` invoice or payor session not found

## Common endpoints

* `/api/v1/payments/session-details`
* `/api/v1/payments/available-tokens`
* `/api/v1/payments/payment-status`
* `/api/v1/payments/payment-addresses`
* `/api/v1/payments/customer-email`

## Related APIs

* Merchant APIs use `x-api-key` for server-side merchant operations.
* Commerce APIs use `x-commerce-api-key` for checkout and order flows.

## Examples

* Poll `/api/v1/payments/payment-status` on a short interval and stop when invoice state becomes terminal (`paid`, `expired`, `cancelled`).

Next: [Available tokens](/api-spec/payors/available-tokens)