Create Payment Intent
Mint a payment intent for the partner org.
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
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
Body
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.
Requested amount in the primary currency. Decimal string preferred to avoid float-precision loss.
x > 0Asset 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.
1 - 10 elementsPartner-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).
255Free-form description, echoed back to the partner.
500Free-form JSON object for partner-side bookkeeping. Capped at 50 keys / 500-char values per key.
Response
Successful Response
Stripe-shaped payment intent envelope.
Payment intent UUID. Pass to GET /payment-intents/:id.
Primary asset code, uppercase (e.g. USDT).
Always payment_intent. Stripe convention.
Requested amount in the intent's primary asset.
Intent status. One of: pending, partial, completed, expired (snake_case, Stripe-compatible).
5-character public-page identifier. Embedded in hosted checkout URLs (zopay.cash/pay/<ref_code>).
Partner-supplied attribution key as passed to POST /payment-intents. Echoed verbatim. Use for your own per-user reconciliation.
Partner-supplied description, echoed verbatim.
Partner-supplied metadata, echoed verbatim. NULL when no metadata was sent at creation.
Per (asset, network) deposit destinations. One row per currency / network pair available on this intent.
When the intent was minted.
When the intent stops accepting deposits.
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.
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.
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.
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.
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.