Skip to navigation
Getting Started

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

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:

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

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

Branch on code, not message.