Skip to main content

Create payment (intent)

POST 
/payments

Creates a PaymentIntent. The merchant hands the returned checkout_url to the buyer (via redirect or link) to start payment. checkout_id is the identifier of the same page; you should not need to assemble a URL yourself.

  • The Idempotency-Key header prevents duplicate creation (24h TTL, Redis-cached).
  • metadata is stored and returned as opaque JSON; CROSS Pay does not interpret it.
  • Pass amount as a string (preserves shopspring/decimal precision).
  • expires_in is in seconds; defaults to 30 minutes when 0 or unset.
  • checkout_url has the form {checkout.base_url}/{checkout_id}, and is omitted from the response in dev environments when checkout.base_url is empty.
  • When country (ISO 3166-1 alpha-2, optional) is supplied, it is forwarded as ?country=XX on the response checkout_url so the hosted checkout page can pre-select the billing country. Not persisted to the DB — the checkout_url on subsequent GET responses will not carry the query.
  • include_pegged_assets (optional, default true since v0.7.55 — previously false) controls whether a fiat-currency payment also offers stablecoins pegged to that fiat (e.g. USD → USDT / USDC / CROSSD) on the hosted checkout. Send an explicit false to keep the checkout fiat-only. Payments whose currency itself is a token symbol (USDT) are unaffected by this flag.

Request​

Responses​

FDS denied the request. The HTTP status stays 200 (this is a business outcome, not a transport-level error) and the body is the { fds: ... } envelope. Any /v1/payments endpoint can return this response.