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

# Payment session (payor)

> Use browser-safe auth to drive the payor checkout flow.

## Overview

Payor routes are designed for client-side checkout and use session-based auth:

* `x-session-token`
* `x-signature`

## Authentication

Payment session auth is derived from invoice creation. Your server creates an invoice and receives:

* `session_token` → use as `x-session-token`
* `signature` → use as `x-signature`

## Request

### Fetch session details

```ts theme={null}
const pepay = new Pepay({
  sessionToken: process.env.PEPAY_SESSION_TOKEN!,
  signature: process.env.PEPAY_SESSION_SIGNATURE!,
  baseUrl: process.env.PEPAY_API_URL ?? 'https://api-beta.pepay.io'
});

const details = await pepay.paymentSessions.getSessionDetails();
```

## Response

Example session details response (truncated):

```json theme={null}
{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_usd": 49.99,
  "description": "Starter plan",
  "expires_at": 1766322000,
  "invoice_status": "unpaid",
  "remaining_time": 3600000,
  "remaining_seconds": 3600,
  "merchant_name": "Pepay Demo Merchant",
  "network_environment": "devnet",
  "locked_network": null,
  "locked_token_id": null,
  "locked_payment_address": null
}
```

Notes:

* `remaining_time` is milliseconds until expiration (clamped at 0).
* `remaining_seconds` is seconds until expiration (clamped at 0).

### Underpaid lock-in

If `invoice_status` is `underpaid`, the response includes:

* `locked_network`
* `locked_token_id`
* `locked_payment_address`

Payors must complete the remaining balance using the locked network/token.

## Errors

* `401` invalid session token/signature
* `404` session not found / expired

## Examples

* Combine `getSessionDetails` with `listAvailableTokens` and `createPaymentAddress` to build a complete payor checkout experience.

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