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

> Session details endpoint for payor checkout flows.

## Overview

Payment session endpoints are designed for **browser/client checkout** experiences. They expose invoice context in a browser-safe way using session headers.

## Authentication

Requires:

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

## Request

Endpoint:

* `GET /api/v1/payments/session-details`

Playground (interactive reference):

* [Payment session details](/api-spec/endpoints/payment-session-details)

Example:

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/v1/payments/session-details" \
  -H "x-session-token: pst_..." \
  -H "x-signature: sig_..."
```

## Response

```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",
  "merchant_email": "billing@example.com",
  "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 with the locked token/network.

## Errors

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

## Examples

* Build checkout screens by combining session details + [Available tokens](/api-spec/payors/available-tokens) + [Payment addresses](/api-spec/payors/payment-addresses).

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