Create a payment intent

post

https://cloud.zenoz.ai/v1/payment_intents

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

amount_cents

integer

required

≥ 50

currency

string

^[a-zA-Z]{3}$

Defaults to usd

rail_code

string

enum

Supported payment rails.

ACH_SD — ACH Same-Day
ACH_ND — ACH Next-Day
FEDNOW — FedNow instant rail
RTP — The Clearing House RTP
AFT_PULL — Account Funding Transaction (pull)
OCT_DOM — Original Credit Transaction, domestic
OCT_XB — Original Credit Transaction, cross-border
CARD — Card rail (generic)
CASH_PICKUP — Cash pickup payout

metadata

object

Your own keys (e.g. order_id), copied onto the payment's transaction at confirm and returned on the transaction detail. Keys the platform writes or reads are reserved and refused with 400 VALIDATION_ERROR, one details.metadata entry per key ('livemode' is a reserved key): any key starting with _, and platform keys such as livemode, experience, source, payment_intent_id, gateway_transaction_id, card_source, card_brand, three_ds_status, fee_type, fee_schedule_ref and the ach_* processing keys. reference is yours to use. Nothing is stripped silently.

customer_id

uuid

. Optional. An active customer of this intent's merchant, created first with POST /v1/merchant/customers. An unknown id, or one belonging to another merchant, answers 404 NOT_FOUND; an inactive customer answers 400 VALIDATION_ERROR. Omit it for a guest payment. Send name, email and address here by reference — never through the hosted card fields.

confirm

boolean

If true, immediately confirm after creation.

merchant_id

uuid

Required only when acting as tenant_owner/tenant_admin without ?merchantId=.

card_instrument_id

string

length ≤ 255

CARD rail: charge a stored card by its vault instrument id. Provide this OR card_token.

card_token

string

length ≤ 255

CARD rail: a one-time card token for a guest / first-time charge. Provide this OR card_instrument_id.

capture_method

string

enum

Defaults to automatic

CARD rail: automatic (default) authorizes and captures on confirm; manual authorizes only — the intent moves to requires_capture and settles via POST /capture.

Allowed:

payment_method

object

Canonical funding reference — a vaulted payment_instruments id, resolved by rail. CARD: resolves the vaulted card's network token (equivalent to card_instrument_id). ACH (ACH_*): resolves a direct-custody bank_account instrument (see POST /v1/tenant/payment-instruments/bank-account), decrypting its account number to originate — no need to pass raw ach_routing_number / ach_account_number_token.

ach_routing_number

string

^[0-9]{9}$

ACH rail: 9-digit ABA routing number (public). Pair with ach_account_number_token.

ach_account_number_token

string

length ≤ 255

ACH rail: the account-number reference for origination. Note: ACH is not zero-custody like cards — the NACHA entry carries the real account number, so this is the account reference (encrypted at rest), not a detokenizable network token.

Headers

Idempotency-Key

string

length ≤ 255

Optional per-merchant idempotency key. Replaying the same key with the same body returns the original intent; a body mismatch returns 409.

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Payment intent created (or replayed on idempotent retry).

400Invalid request payload or query parameters.

401Missing or invalid authentication credentials.

403Caller lacks the required role/permission for the resource.

404NOT_FOUND — customer_id is unknown or belongs to another merchant.

409Request conflicts with current resource state (e.g. duplicate key, stale version).

422Amount below the minimum (50 cents) or other semantic validation error.

429RATE_LIMITED — CARD intents are throttled while the merchant's hosted-fields decline-rate breaker is tripped (card-testing signal); clears after the cool-down.

500Unexpected server error.