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

Some endpoints support the optional Idempotency-Key header. 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 → 422 IDEMPOTENCY_CONFLICT.
• Omitting the key is permitted — the caller accepts all retry and duplicate risk.

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:

1
{ "<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:

1
{ "error": { "code": "QUOTE_EXPIRED", "message": "...", "details": {} } }

Branch on code, not message.