Skip to main content
POST
Create Payment Intent
Mint a payment intent for the partner org. Idempotency: the Idempotency-Key header is required for this endpoint (enforced by idempotency_required). Same key + same body within 24h replays the original response verbatim. Same key + different body returns 409 idempotency_conflict. Unlike the address-creation flow, the underlying intent create is NOT idempotent on its own (it mints a fresh ref_code per call, so a naive retry would create two intents). The Idempotency-Key store is the only safety net here — without the header a retry mints a second intent. Partners SHOULD send the header on every POST. Dependency order: idem is taken before auth so the Idempotency-Key header is parsed (which can 400 on its own) before the DB hit for the scope check. Sandbox routing: sk_test_… keys (auth.mode == "sandbox") are routed to ConnectPaymentIntentsSandboxService, which makes no payment-server / BitGo / Rhino calls and persists the intent with deterministic fake addresses. sk_live_… keys continue to hit the real path through PaymentIntentService.create_payment_link.

Authorizations

Authorization
string
header
required

Paste your Connect API key (sk_live_… for production, sk_test_… for sandbox) without the Bearer prefix. Mint and rotate keys from the admin panel.

Headers

Idempotency-Key
string | null

Body

application/json

Request body for POST /connect/v1/payment-intents.

Forbidden extras: typo'd field names surface as a 422 rather than being silently ignored. Partners can recover by checking their request body shape against the docs.

All amount handling is in the intent's primary currency (currencies[0]). Multi-currency intents accept the same nominal amount across every currency -- there is no per-currency pricing slot here. If a partner needs per-currency pricing they can either mint one intent per currency or call a future quote API.

amount
required

Requested amount in the primary currency. Decimal string preferred to avoid float-precision loss.

Required range: x > 0
currencies
string[]
required

Asset codes the intent will accept, in priority order. First entry is the primary currency (drives the merchant-facing amount column). Each currency expands to all active networks server-side.

Required array length: 1 - 10 elements
external_ref
string | null

Partner-supplied attribution key. Stamped on the intent so webhooks and list filters can correlate back to your internal user. Omit if no per-user attribution applies (e.g. tenant-treasury collection page).

Maximum string length: 255
description
string | null

Free-form description, echoed back to the partner.

Maximum string length: 500
metadata
Metadata · object | null

Free-form JSON object for partner-side bookkeeping. Capped at 50 keys / 500-char values per key.

Response

Successful Response

Stripe-shaped payment intent envelope.

id
string
required

Payment intent UUID. Pass to GET /payment-intents/:id.

currency
string
required

Primary asset code, uppercase (e.g. USDT).

object
string
default:payment_intent

Always payment_intent. Stripe convention.

amount
number | null

Requested amount in the intent's primary asset.

status
string | null

Intent status. One of: pending, partial, completed, expired (snake_case, Stripe-compatible).

ref_code
string | null

5-character public-page identifier. Embedded in hosted checkout URLs (zopay.cash/pay/<ref_code>).

external_ref
string | null

Partner-supplied attribution key as passed to POST /payment-intents. Echoed verbatim. Use for your own per-user reconciliation.

description
string | null

Partner-supplied description, echoed verbatim.

metadata
Metadata · object | null

Partner-supplied metadata, echoed verbatim. NULL when no metadata was sent at creation.

addresses
ConnectPaymentIntentAddress · object[]

Per (asset, network) deposit destinations. One row per currency / network pair available on this intent.

created_at
string<date-time> | null

When the intent was minted.

expires_at
string<date-time> | null

When the intent stops accepting deposits.

completed_at
string<date-time> | null

When the intent transitioned to status='completed'. NULL while pending. Idempotency anchor for the completion transition -- a retried call sees the same value, never a fresh one.

deposit
ConnectPaymentIntentDeposit · object | null

Chain-side details of the deposit that fulfilled this intent. NULL while pending; populated on completion. Field-for-field parity with the payment_intent.completed webhook event payload so pull and push reconciliation see one shape. On a partial-then-complete intent this object reflects the LATEST deposit, not the cumulative total; use amount_received for the cumulative figure.

amount_received
number
default:0

Cumulative amount credited against this intent across all completed deposits. Always present; defaults to 0.0 when nothing has landed yet. On a partial payment this is the partial total; once the intent transitions to completed it equals (or slightly exceeds, by up to the 0.01 tolerance) amount.

amount_remaining
number
default:0

Raw remaining amount: max(0, amount - amount_received). No tolerance applied -- partners that want to render a 'pay X more' UI should check partial_payment first and read this value as the literal shortfall. A near-complete intent within the 0.01 tolerance shows a small positive value here but partial_payment=false.

partial_payment
boolean
default:false

True iff the intent has received at least one deposit but is not yet completed: amount_received > 0 AND status == 'pending'. Use this as the canonical 'is incomplete' boolean for partial-payment UI. Tolerance is handled transitively through status: the credit flow only leaves the intent in pending when the cumulative received amount is below the (amount - 0.01) threshold, so a near-complete intent within tolerance has already transitioned to completed and surfaces as partial_payment=false here.