API ReferencePayments Intents

Create Intent

View as Markdown
Create a payment intent. Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.
customer_idstringRequired
amount_atomintegerRequired
currencyenumRequired
ISO 4217 currency codes.
payment_method_idstring or nullOptional
processor_idstring or nullOptional
metadatamap from strings to any or nullOptional

Response

Successful Response
idstring
account_idstring
customer_idstring
amount_atominteger
currencyenum
ISO 4217 currency codes.
statusstring
client_secretstring or null
confirmed_atdatetime or null
metadatamap from strings to any or null
created_atdatetime
updated_atdatetime
display_statusstringOptionalDefaults to

Merchant-facing status label derived from internal state + creation context. Render this in UIs — never the raw status.

tooltip_keystring or nullOptional

Explicit key the frontend maps to tooltip copy (Decision Q4). None where no tooltip is shown (SUCCEEDED, EXCEPTION).

created_viastring or nullOptional

Write-once provenance: how this payment intent was created (checkout, checkout_setup, invoice, api, migration).

cancellation_reasonstring or nullOptional

Why a cancelled payment intent was cancelled (hold_released, expired, payment_cancelled). None unless the intent was cancelled.

amount_atom_capturableintegerOptionalDefaults to 0
amount_atom_receivedintegerOptionalDefaults to 0
amount_atom_refundedintegerOptionalDefaults to 0
Total refunded amount
refunded_atdatetime or nullOptional

When the latest successful refund happened (None if never refunded)

attempt_countinteger or nullOptionalDefaults to 0
Number of processor attempts
invoiceslist of objectsOptional
customer_emailstring or nullOptional
Customer email address
payment_methodobject or nullOptional

Payment method used (from latest attempt)

processorobject or nullOptional

Payment processor used (from latest attempt)

decline_reasonstring or nullOptional
Decline reason from latest failed attempt
failure_codestring or nullOptional

Machine-readable failure code from the latest failed attempt (e.g. ‘currency_unsupported’). Lets the UI render a specific, localizable reason. None when no coded failure is available.

binstring or nullOptional

Card BIN/IIN — the issuer prefix of the card number, 6 or 8 digits depending on the network. Sourced from the card itself, so it is the same value for a given card regardless of which processor handled the payment, and is present on declined payments too. Exposed for CSV export; not shown in the in-app payments table. None for non-card methods, or for cards saved before this data was captured.

is_merchant_initiatedboolean or nullOptional

Whether this is a merchant-initiated transaction (MIT). False = customer-initiated (CIT). None = unknown/legacy.

Errors

422
Unprocessable Entity Error