> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/conventions/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Conventions

## Overview

Below are some common patterns used across all CrissCross API endpoints.

### Identifiers

All identifiers issued by the Payments side of the API — `sessionId`, `transactionId`, `originalTransactionId`, refund transaction ids, and so on — are **UUID v7** strings.

```
01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70
```

UUID v7 prefixes the value with a millisecond Unix timestamp, so identifiers are time-sortable. There are no prefixes (e.g. `txn_…`) or other formats in use. Treat them as opaque strings when storing or comparing them.

### Idempotency

The optional `Idempotency-Key` header is supported only where an endpoint's API reference explicitly says so (currently select Exchange endpoints, such as beneficiary creation). Where supported, send a client-generated UUIDv4 that you persist locally before issuing the request and reuse on any retry:

* Same key + same body → original response returned; no duplicate side effect.
* Same key + different body → `IDEMPOTENCY_CONFLICT`.

On all other endpoints the header is ignored. Duplicate protection there works differently per product:

* **Collect**: session `merchantReference` is unique per merchant — creating a second session with a used reference is rejected with `409 DUPLICATE_REFERENCE` carrying the existing `sessionId`, so retrying with the same reference is a safe probe for whether the original creation succeeded. One caveat: references first used before uniqueness was enforced may be shared by several legacy sessions, and the 409 returns the most recent — verify the returned session before treating it as confirmation. See [Payment Status & Recovery](/collect/payment-recovery).
* **Payouts**: idempotency is keyed on your `merchantReference`, which must be unique per merchant — retrying a payout with the same reference is rejected with `409 DUPLICATE_REFERENCE`, confirming the original was accepted. See [Single Payouts](/payout-single#idempotency).

### Pagination

All list endpoints use cursor pagination. Use `limit` (default 20, max 200) and `cursor` (opaque string from `nextCursor`). List responses are wrapped in a named envelope:

```json
{ "<resource>": [...], "nextCursor": "eyJ...", "hasMore": true }
```

### Timestamps

All timestamp fields are ISO 8601 strings in UTC (e.g. `"2026-04-21T14:15:30Z"`). Clients should treat any offset other than `Z` as an error.

### Error envelope

All errors use:

```json
{ "error": { "code": "QUOTE_EXPIRED", "message": "...", "details": {} } }
```

Branch on `code`, not `message`.