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

# API conventions

> Envelopes, amounts, pagination, idempotency and rate limits.

Everything in the API follows the same handful of rules. Read this once and the rest of the
reference reads itself.

Base URL: `https://api.orqex.com/v1`

## Response envelopes

A write returns a message and the resource:

```json theme={null}
{ "message": "...", "data": { "id": "pi_..." } }
```

A read returns the resource alone:

```json theme={null}
{ "data": { "id": "pi_..." } }
```

A list returns an array and a pagination block:

```json theme={null}
{ "data": [ ... ], "pagination": { ... } }
```

## Amounts

Every amount in a **response** is an object, so you never have to format it yourself:

```json theme={null}
{
  "value": 50,
  "formatted": "$50.00",
  "short": "$50",
  "currency": "USD"
}
```

Amounts in a **request** are plain numbers in **major units**, on every resource — payment
intents, checkout sessions, refunds and payouts alike. `50` means 50.00, never 0.50.

The minimum is `1`.

## Pagination

Lists are cursor-paginated. Pass `per_page` to size the page, and follow `next_cursor` or
`next_page_url` to walk forward.

```json theme={null}
{
  "count": 25,
  "path": "https://api.orqex.com/v1/payment/intents",
  "per_page": 25,
  "next_cursor": "eyJpZCI6...",
  "next_page_url": "https://api.orqex.com/v1/payment/intents?cursor=eyJpZCI6...",
  "prev_cursor": null,
  "prev_page_url": null,
  "has_more_pages": true,
  "has_pages": true
}
```

Stop when `has_more_pages` is `false`. Cursors are opaque — do not parse or construct them.

## Idempotency

Send `X-Idempotency-Key` on any `POST` to make a retry safe. The key is a string you choose,
8 to 128 characters, unique per logical operation.

```bash theme={null}
curl -X POST https://api.orqex.com/v1/payment/intents \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Idempotency-Key: order-1042-intent" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

The first response is stored for 24 hours. Repeating the request with the same key replays
that stored response — same status, same body — and adds `X-Idempotent-Replayed: true`. No
second payment is created.

Use it wherever a network timeout would otherwise leave you unsure whether the call landed:
creating intents, attempts, refunds and payouts. Safe methods (`GET`) ignore the header.

## Rate limits

100 requests per minute per API key. Over the limit, the API returns `429`; back off and
retry.

## Timestamps and identifiers

Timestamps are ISO 8601. Identifiers are opaque strings with a resource prefix (`pi_` for a
payment intent, `rq_` for a requery, and so on). Treat them as strings; do not infer meaning
from their contents beyond the prefix.