commerce
POST /v1/orders/{orderId}/pay
Pay an order that was placed but not charged.
Authentication
Send an API key as a bearer token. The endpoint checks billing.payment.manage; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/orders/{orderId}/pay \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Charges an order left pending_payment (or retries one that is payment_failed), wallet credit first and the remainder on the org's default mandate. This is where the guest funnel's next: "payment" step lands: checkout converts the cart when it places the order, so the cart endpoint cannot settle it afterwards and this is the only surface that can. Idempotent without an Idempotency-Key, unlike checkout. The order already exists and is itself the dedup scope, so a double-submit records the same capture rather than taking a second one. A pay attempt against an already-paid order returns that order unchanged rather than an error. A declined card answers 200, not 402: the attempt was processed exactly as asked and the order comes back payment_failed for the caller to read. Only the platform being unable to charge at all — no gateway configured, or one an operator has deliberately disabled — is a 503. Choosing a gateway. Send gateway to settle this order on a specific rail rather than the org's default mandate — the owner's "settle overdue bills with any gateway they like". It must be one of getOrderPaymentOptions's entries, which is why a reseller's client (who has exactly one) cannot be re-routed. Rails that finish in the browser — PayPal approval, a crypto invoice — answer 200 with the order still pending_payment and a customer_action carrying the URL to send the customer to; the order settles when the gateway's webhook confirms it.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
orderId (path) | Uuid | Yes | The order's id. |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
gateway | string | No | The rail to settle on (stripe, paypal, nowpayments). Omit to use the org's nominated payment method. 422 if it is not one of this order's getOrderPaymentOptions. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
id | Uuid | Yes | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | Yes | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
human_ref | string | Yes | Human-friendly order reference. |
status | OrderStatus | Yes | An order's lifecycle state (docs/31 §4.3). |
currency | CurrencyCode | Yes | ISO 4217 currency code (money is minor units + this code — CLAUDE.md §2.8). |
subtotal_minor | integer | Yes | — |
tax_minor | integer | Yes | — |
discount_minor | integer | Yes | — |
total_minor | integer | Yes | — |
billing_country | object | No | — |
placed_at | object | No | — |
created_at | string | Yes | — |
updated_at | string | No | — |
lines | OrderLine[] | Yes | — |
payments | Payment[] | Yes | — |
coverage | PaymentCoverage | null | No | What paying this order buys, said BEFORE the customer pays (s1014 R40, docs/747 §2a): the subscription period it covers, the periods still owed after it, and whether the services… |
customer_action | object | No | Present only when the attempt needs the customer to finish it in a browser (PayPal approval, a crypto invoice, a 3-D Secure step). Short-lived and never stored — request it again… |
Errors this endpoint can return
401 · 403 · 404 · 422 · 429 · 503