Create Order

Creates a payment. One endpoint handles every flow — collect, pay out, on-ramp, off-ramp, pre-fund and swap — and orderType selects which. Register the user first, put the amount in source or destination (never both), and send a unique partnerId so a retry can never create a duplicate.

Error cases

A 400 carries the specific reason in error.context.details[].code.

  • STANDARD_KYC_REQUIRED / ENHANCED_KYC_REQUIRED: The user has reached a limit. Start that verification level, then create the order again once it succeeds.
  • PARTNER_ID_ALREADY_USED: This partnerId already belongs to an order. Do not create it again; find the existing order with List Orders.
  • SUCCESS_REDIRECT_URL_REQUIRED: Send successRedirectUrl, or set a default redirect URL in the dashboard.
  • SOURCE_CURRENCY_NOT_SUPPORTED: Use a currency returned by List Supported Currencies or List Tokens.
  • PAYMENT_METHOD_NOT_FOUND: Fetch the methods for this country and direction with List Payment Methods, and use the codes returned.
  • INSUFFICIENT_BALANCE: Pre-fund your balance, then create a new order.
  • QUOTES_EXPIRED: Request a fresh rate and create the order again.
  • DEVICE_DETAILS_REQUIRED: Headless and card flows need deviceDetails.
  • IP_VALIDATION_FAILED: The payer's IP address failed validation for this flow. Check the device details you send; contact support if it continues.
  • DECLINED_BY_BANK_SUSPECTED_FRAUD: The bank declined the transaction. Show the message to the user and do not retry the same payment.
  • BANK_REVIEW: The transaction is under review by the bank. Try again after 24 hours.
  • TRANSACTION_REVIEW: The account is under review because of crypto-monitoring alerts. Try again after 24 hours.
  • Compliance check failed: Show the message to the user. Do not retry; contact support if you believe it is wrong.

Used in: Collections · Payouts · On-Ramp & Off-Ramp · Pre-funding · MCA

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string

Your own unique reference for the order. Optional but strongly recommended. A value that has already been used is rejected with PARTNER_ID_ALREADY_USED, so a retry can never create a second order.

string
^UX-

The user this order is for. Required for onramp, offramp, payin, payout, swap and gaming orders. For a third-party on-ramp or off-ramp, omit it and send source.userId and destination.userId instead.

string
^IN-

The ID returned by Upload Documents (POST /v3/invoices/create). Attach it to a payin or payout that needs a supporting document.

customerMetaData
object

Optional. Any data of your own; it is stored with the order and returned on it.

string

Optional. For payin and gaming orders only. The settlement account your collected funds are paid out to. Its currency must match destination.currency.

string
required

Why the money is moving. See Purpose Codes; use other with purposeCodeReason when nothing fits.

uri

The URL of your website that the payer comes from. Must start with https://.

uri

Where the payer is sent after a successful payment. Must start with https://. Not needed if a default redirect URL is set in the dashboard under Settings → Integration; if you send it, it overrides that default. If no default is set, it is required for gaming orders, and for onramp, offramp, payin and swap orders when headlessMode is false.

uri

Where the payer is sent after a failed payment. Must start with https://. Not needed if a default redirect URL is set in the dashboard under Settings → Integration; if you send it, it overrides that default. If no default is set, it is required for gaming orders, and for onramp, offramp, payin and swap orders when headlessMode is false.

deviceDetails
object

Details of the payer's device. Optional for hosted flows; required for headless and card flows.

customization
object

Optional. Display options for the hosted payment page.

boolean
Defaults to false

Optional. Defaults to false. When true, the payer is not sent to a hosted payment page: you collect the payment details yourself, and you must send everything the payment method requires in source. Relevant for payin, swap, onramp and offramp orders.

string
enum
required
ValueMeaning
onrampYour user buys crypto with local currency
offrampYour user sells crypto for local currency
payinA customer pays you (collection)
payoutYou pay a person or business from your balance
fiat_prefundYou add your own fiat to your balance
crypto_prefundYou add your own crypto to your balance
swapYou convert a balance you hold into another currency
gamingA customer pays you through a custodial wallet created in their name
source
object
required

Where the money comes from: the currency and, for fiat, the payment method. Set amount here or on destination, never both.

destination
object
required

Where the money goes: the currency, and the payment method or wallet. Set amount here or on source, never both.

Headers
string
required

Your merchant ID (MID). Required on every request; it scopes the call to one merchant or sub-merchant.

Responses

401

Unauthorized. Add the MID header, and check the Base64 credentials and that they belong to this environment.

429

Too many requests. Wait, then retry: 1 second, then 2, then 4.

Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json