POST · Billing & invoices
Hold a card payment for confirmation
Hold a card payment for confirmation
/api/v1/invoices/{invoice}/actions/pay-with-card
Description
Previews the charge (amount + which saved card), then returns {status:"confirmation_required", confirmationUrl, …}. It charges nothing on this call. On approval the card is charged off-session and the result carries an honest paymentStatus after the invoice is polled.
Path parameters
| Name | Type | Description |
|---|---|---|
invoice
required
|
string |
Body
Send as application/json.
| Name | Type | Description |
|---|---|---|
invoice_id
required
|
integer |
The numeric invoice id to pay. Get it from list_invoices → data[].id.
|
card_id
|
integer |
Which saved card to charge, from get_invoice_payment_methods → cards[].id. Omit to use the account default card.
|
attempt_key
|
string | Idempotency key for this intent. Keep it stable across retries so a timed-out retry cannot buy the same thing twice. Up to 128 characters. |
Responses
A 200 response returns the shape shown in the rail.
Every non-2xx response is an RFC 7807 problem with a stable
code.
Commonly returned errors
The codes this operation reaches on its own path: the auth stack, its own validation and
ownership checks, and the transport. Not a closed set — a shared code from the
full registry can still surface. Each links to the code’s own page,
the same URL its type dereferences to.