Endpoints

This catalog lists the merchant-facing API operations grouped by resource. Each operation is described by its kind (command or query), its result class, and its canonical inputs and fields — using the exact field names the API accepts and returns.

Operations are described semantically. The envelope, status mapping, error codes, authentication, idempotency, and pagination contracts are fixed once and apply to every operation below:

• Envelope and result classes — Conventions
• Authentication — Authentication
• Idempotency — Idempotency
• Pagination and filtering — Pagination and filtering
• Error codes and HTTP mapping — Errors
• Limits — Reference › Rate limits

Reading rules for every row:

• Result class is one of singleton, collection, or ack (Conventions). A command that creates a new resource returns 201; every other success returns 200.
• Selectors and filters use the exact canonical field names. Unknown parameters are rejected as VALIDATION_ERROR.
• A singleton selector that resolves to nothing returns NOT_FOUND. A collection that matches nothing returns an empty data: [], not an error.
• Collection reads page through results with limit and cursor where the surface supports pagination.

---

Payment intents

A payment intent is the entry point of a payment, anchored by payment_intent_id.

Create — request body

Re-using an idempotency_key with different semantic input returns IDEMPOTENCY_CONFLICT.

Payment intent — result fields

Any status label on a payment intent is a projection label, not write-model truth. Cancellation is recorded as intent status history; it does not mean payment failure.

Intent status history — result fields

History is append-only audit truth; it is not payment finality truth.

---

Payment attempts

A payment attempt is an expected on-chain execution under a payment intent, anchored by attempt_id.

Payment attempt — result fields

Attempt records are expected-execution truth, not settlement truth. Additional persisted fields may be present.

---

Checkout sessions

A checkout session is the checkout context for one payment intent, anchored by session_id.

Checkout session — result fields

---

Payment status summary

A composite, read-only status view rooted at one payment_intent_id, for status rendering.

The summary combines the intent expectation, the relevant session and attempt projection fields, and any materialized outcome projection. Settlement-style labels in this view — PAID, FAILED, DUPLICATE_PAYMENT — are projections derived from the canonical finality outcome and MUST NOT be treated as authoritative settlement truth. The canonical record is the Proof of Payment. When no session or attempt context exists yet, only the intent-root summary is returned.

---

KYT decisions

The merchant's own KYT decisions, read back. get resolves one decision; list returns the full decision history for an attempt.

list is ordered by received_at ascending. Decisions are append-only per attempt; the effective decision is the record with the latest received_at. Position alone does not imply applicability.

KYT decision — result fields

---

Proof of Payment

The canonical, blockchain-derived record of a payment event, anchored by pop_id. For record contents and verification, see Proof of Payment and Verifying a PoP.

A single payment_intent_id may correlate to more than one record (duplicate analysis across attempts). The confirmed_at range is interpreted against the record's confirmation timestamp.

---

Webhook endpoints

A webhook endpoint is a registered notification destination, anchored by endpoint_id. Its signing secret is anchored by signing_secret_id. For delivery and verification semantics, see Notifications.

Endpoint — result fields

The url is immutable. To change a destination, register a new endpoint and disable the old one. A disabled endpoint receives no deliveries.

Signing secret — result fields (metadata only)

At most one active signing secret exists per endpoint: generating or rotating invalidates the prior secret. Read surfaces never return secret material.

---

API keys

A merchant API key authenticates calls, anchored by api_key_id.

API key — result fields (metadata only)

At most one active key exists per merchant: generating a new key invalidates the prior one. A key is active while revoked_at is null. Read surfaces never return key material.