Choose the payment shape
For an on-ramp, put the crypto address in
recipient_fields.address.
Fiat-to-fiat supports this two-hop shape only. Do not create a separate merchant
payment for the intermediate transfer or request identical source and destination
assets.
Discover live instruments through
List fiat payment capabilities,
not a static currency list alone. Before a fiat payout, use
Parse QR recipient or
Verify bank recipient, as applicable,
and carry the returned canonical recipient_fields into payment creation.
Estimate before commitment
Estimate payment owns the quote request and response examples, includingpreferred_rails. Send the end user and the
supported on_ramp or off_ramp direction with exactly one of amount_in or
amount_out.
An estimate filters by end-user readiness but is non-binding. It does not
reserve a route or authorize funds to move. Request it near checkout, then
create the payment when the customer commits.
Create one commercial order
Create payment owns the complete request and response contract. Supply the merchant end user, your request correlation ID, durablemerchant_payment_reference, source and destination assets, amount
mode, and final recipient.
Choose exact_source when the payer fixes how much to spend; put that amount in
source. Choose exact_destination when the customer fixes how much must
arrive; put that amount in destination. Amounts are strings.
For a QR recipient, country is normally derived from qr_content; an optional
country constraint must match. A direct bank recipient requires country.
Never add a client-selected internal rail. Recipient validation happens again
when the payment is created, without using a saved recipient book.
Use one payment reference per economic order and reuse the same body and
reference after an uncertain request. See
Payment idempotency.
Follow the returned payment
The server-generatedpayment_instruction is the funding authority;
next_action tells the customer whether to fund or wait. Preserve the issued
amount, asset, destination, chain, memo, reference, calldata, and expiry.
Funding and tracking explains how to present the
instruction and reconcile webhooks with current payment state.
Use Get payment for the full current view
and List payments for merchant history and
its supported filters. Portal JWT holders can also
read and list
payments, but cannot create or cancel them.
Cancellation and active-payment limits
Cancel payment applies before funding where the current settlement state permits it. Do not report success until the returned or subsequently read payment is terminal withstatus: "cancelled".
Each end user may have only one non-terminal B2B payment, regardless of direction
or hop count. Complete, cancel, or let it reach a terminal state before creating
another. Internal fiat-to-fiat hops are not separate merchant orders.