A contract an engineer can inspect.
Build a payment-intent workflow you can inspect: create the request, read its state and understand how retries and errors behave.
Create a payment intent
The selected POST contract requires Content-Type application/json, a verified application session, payment.create authority and a valid Idempotency-Key. The key is scoped to the organization and an operation containing the caller’s identity. Creation returns 201 and the IntentView object; it does not collect money.
{
"amount": { "amountMinor": "250000", "assetId": "synthetic_asset_placeholder" },
"orderReference": "evaluation-order-0001",
"description": "Synthetic evaluation order",
"expiresInMinutes": 30
}
// Shape example only. Placeholder IDs are not valid for execution.| Field | Type / requirement | Meaning |
|---|---|---|
| amount.amountMinor | Required string; canonical positive integer. | No decimal, exponent, sign, leading zero or whitespace; not a float. |
| amount.assetId | Required string; existing environment-compatible asset. | Physical cash is excluded from payment intents. |
| orderReference | Required nonblank string; maximum 120 characters before trimming. | Merchant order reference; trimmed before storage. |
| description | Optional string; maximum 500 characters. | Omission becomes null in the response. |
| expiresInMinutes | Optional integer 1–10080; omitted or null defaults to 30. | Requested intent expiry, not a provider execution deadline. |
Read a list or one record
The list uses status, q, limit, from and to. Default limit is 50; maximum is 200 without a date range and 1000 with a range. A range requires both valid YYYY-MM-DD dates with from ≤ to. q is at most 120 characters. Results are newest-created first. No cursor or complete-history export guarantee is defined by this list contract.
Dates are inclusive calendar days in America/Port-au-Prince. The current predicate includes records created before the end-day boundary when creation or confirmation is on/after the start-day boundary. Confirmation has no separate upper bound: an older record confirmed after the requested end date can therefore appear. This is not interchangeable with the reconciliation view, which groups payments by confirmation day and statement evidence.
| IntentView fields | Representation |
|---|---|
| id, amount, orderReference | Identifier, { amountMinor, assetId }, merchant reference. |
| description, providerConnectionId, confirmedAt | Nullable fields; timestamps use ISO strings. |
| status, settlementStatus, environment | Separate payment state, settlement state and environment. |
| expiresAt, createdAt, createdBy | ISO timestamps and creating user identifier. |
| Detail-only attempts and receipt | Attempt history; receipt object or null. List adds provider/providerLabel instead. |
Submission is not confirmation.
Starting an attempt requires providerConnectionId, payment.collect authority and its own idempotency key. The 201 response contains attemptId and providerReference. Durable work later submits to the provider; do not treat this response as payment success. Cancellation requires JSON, an idempotency key and payment.cancel authority. An unresolved attempt blocks cancellation.
- Intent states: requires_payment, processing, requires_review, succeeded, failed, canceled, expired.
- A repeated identical key/body replays the stored status/body and adds idempotent-replayed: true. A changed body with the same key returns idempotency_conflict (409).
- The selected common JSON wrapper returns cache-control: no-store and x-request-id. Core failures contain error.code, error.message and error.requestId; unknown failures return a generic internal_error (500).
Choose the recovery from the code.
These are core mappings, not a claim that every endpoint produces every code. A transient transport failure does not prove that an operation was rejected.
| Code / HTTP | Evaluation action |
|---|---|
| invalid_request / 400 | Correct the field or content type; review the selected contract. |
| unauthenticated / 401; forbidden / 403; not_found / 404 | Check verified session and current scope. A scoped 404 does not establish global nonexistence. |
| idempotency_conflict / 409; invalid_transition / 409 | Inspect the original request and current state; do not bypass with a new charge. |
| asset_mismatch, environment_mismatch, capability_disabled, quote_expired / 422 | Resolve asset/environment/grant/quote prerequisites before resubmission. |
| unbalanced_journal / 422 | Escalate the financial-record failure; do not invent a balancing movement. |
| rate_limited / 429; provider_unavailable / 503; internal_error / 500 | Preserve request identity; use agreed lookup/backoff and inspect whether submission occurred. |
The selected JSON contract snapshot.
Selected request/response schemas and operations. Documentation only; no calls or credentials.