Create order

Create a crypto purchase order and get a redirect URL to the purchase page.

Usage of return URLs

The request and response may contain return URLs such as the returnSuccessUrl and returnFailedUrl parameters, whose usage depends on a provider. Both parameters have URL validation.

Usage of returnSuccessUrl and returnFailedUrl

providerCode	Type of usage
`moonpay`	After a completed transaction, Moonpay redirects a user to the `returnSuccessUrl` or `returnFailedUrl` URL. It appends the transaction's ID and status to the URL as query parameters. Also, it is possible to pass deeplinks and other custom parameters.
`banxa`	After a completed checkout, Banxa redirects a user to the `returnSuccessUrl` or `returnFailedUrl` URL. It doesn't append anything to the URL as query parameters.
`transak`	After a completed transaction, Transak redirects a user to the `returnSuccessUrl` or `returnFailedUrl` URL. It appends additional order info to the URL as query parameters. More details about the return URLs in the official Transak documentation.
`wert`	Wert doesn't redirect and append anything to the URL as query parameters. It only shows a button 'Back' leading to the `returnSuccessUrl` or `returnFailedUrl` URL.

HTTP request

post

/v1/orders

Request

Header parameters

Requires authentification.

Body parameters

Name	Type	Required	Description
amountFrom	string	true	Amount of currency the user is going to pay.
country	string	true	Country ISO 3166-1 code (Alpha-2).
state	string	false	State ISO 3166-2 code. Is required if provided `country` is `US`.
currencyFrom	string	true	Ticker of the payin currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
externalOrderId	string	true	Order ID provided by you.
externalUserId	string	true	User ID provided by you.
providerCode	string	true	The On-Ramp provider code. Possible values.
walletAddress	string	true	Recipient wallet address. Here are 2 simple use cases of this parameter: If you want to provide the cryptocurrency purchase service, you should enable the user to specify the wallet address. If you want to sell your products for fiat and receive cryptocurrency in your wallet, you should specify your own wallet address.
walletExtraId	string	false	Property required for wallet addresses of currencies that use an additional ID for transaction processing (XRP, XLM, EOS, BNB).
ip	string	false	User's IP address.
metadata	object	false	Metadata object, which can contain any parameters you need.
paymentMethod	string	false	The payment method code. Possible values.
returnSuccessUrl	string	false	Return URL after a successfully completed transaction.
returnFailedUrl	string	false	Return URL after a failed transaction.
userAgent	string	false	User Agent.

Learn more details about the returnSuccessUrl and returnFailedUrl parameters.

Sample payload

application/json
{
  "externalOrderId": "test_tx",
  "externalUserId": "test_user",
  "providerCode": "moonpay",
  "currencyFrom": "USD",
  "currencyTo": "BTC",
  "amountFrom": "150",
  "country": "NL",
  "walletAddress": "...",
  "paymentMethod": "card",
  "returnSuccessUrl": "https://example.com/success",
  "returnFailedUrl": "https://example.com/failed"
}

Sample cURL

curl --location --request POST
'https://fiat-api.changelly.com/v1/orders'
--header 'X-Api-Key: {{apiKey}}'
--header 'X-Api-Signature: {{signature}}'
--data-raw '{
  "externalOrderId": "test_tx",
  "externalUserId": "test_user",
  "providerCode": "moonpay",
  "currencyFrom": "USD",
  "currencyTo": "BTC",
  "amountFrom": "150",
  "country": "NL",
  "walletAddress": "...",
  "paymentMethod": "card",
  "returnSuccessUrl": "https://example.com/success",
  "returnFailedUrl": "https://example.com/failed"
}'

Response

info

If any of the optional parameters are not provided in the request, they will be returned with the null value in the response.

Response params

Name	Type	Required	Description
amountFrom	string	true	Amount of currency the user is going to pay.
country	string	true	Country ISO 3166-1 code (Alpha-2).
state	string	false	State ISO 3166-2 code. Is required if provided `country` is `US`.
createdAt	date-time	true	Time in ISO 8601 format.
currencyFrom	string	true	Ticker of the payin currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
externalUserId	string	true	User ID provided by you.
ip	string	true	User's IP address.
metadata	object	true	Metadata object, which can contain any parameters you need: If you don't provide the `metadata` object in the request, `null` will be returned in `metadata` in response. If you specify an empty object in the request, an empty object will be returned in the response.
orderId	string	true	Internal order ID provided by Fiat API.
externalOrderId	string	true	Order ID provided by you.
paymentMethod	string	true	The payment method code. Possible values.
providerCode	string	true	The On-Ramp provider code. Possible values.
redirectUrl	string	true	URL to the provider's purchase page.
refundAddress	string	true	Recipient refund address.
type	string	true	Enum: `buy`/`sell`. Order type.
userAgent	string	true	User Agent.
walletAddress	string	true	Recipient wallet address.
walletExtraId	string	true	Property required for wallet addresses of currencies that use an additional ID for transaction processing (XRP, XLM, EOS, BNB).
returnFailedUrl	string	false	Return URL after a failed transaction.
returnSuccessUrl	string	false	Return URL after a successfully completed transaction.

Learn more details about the returnSuccessUrl and returnFailedUrl parameters.

Sample response

application/json
{
  "redirectUrl": "https://buy.moonpay.com/changelly?...",
  "returnFailedUrl": "https://example.com/failed",
  "returnSuccessUrl": "https://example.com/success",
  "orderId": "f7ad32dd-8e1a-47e1-8a2b-72b0f7f0186a",
  "externalUserId": "test_user",
  "externalOrderId": "test_tx",
  "providerCode": "moonpay",
  "type": "buy",
  "currencyFrom": "USD",
  "currencyTo": "BTC",
  "amountFrom": "150",
  "country": "NL",
  "state": "None",
  "ip": "None",
  "walletAddress": "...",
  "walletExtraId": "None",
  "refundAddress": "None",
  "paymentMethod": "card",
  "userAgent": "None",
  "metadata": "None",
  "createdAt": "2025-10-06T11:43:56.619Z"
}

Error response

Error response parameters

Check the error response schema.

Possible error types in the errorType item:

Type	Description
currency	Specified currency pair is not supported by the provider.
initialize	Failed to save transaction.
invalidOffer	On-Ramp provider returned an invalid offer.
outOfLimits	Specified payin amount is less than the minimum or more than the maximum value for the fiat currency.
validation	Validation error.
timeout	Request to the provider was not completed in the allotted time.
paymentMethod	Specified payment method is not supported by the provider.
state	Offer requested for the United States, but the `state` parameter is not provided.
unavailable	Request failed at the provider's end.
unknownError	Unknown error.
unsupportedCommissionRate	On-Ramp provider does not support commission rate.
unsupportedCountry	Specified country is not supported by the provider.
unsupportedExchangePair	On-Ramp provider does not support provided exchange pair.

The errorDetails item schema:

Name	Type	Required	Description
cause	string	true	Error cause. For example, it can equal `min` or `max` for the outOfLimits error type.
value	string	true	Error value. For example, it can equal the min or max supported value for the outOfLimits error type.

Error codes

Code	Message
400	Bad request
401	Unauthorized
404	Not found
422	Unknown error
429	Too many requests
500	Internal server error

Bad Request
{
  "errorType": "outOfLimits",
  "errorMessage": "Limits error",
  "errorDetails": null
}

Unauthorized
{
  "errorType": "unauthorized",
  "errorMessage": "Unauthorized",
  "errorDetails": null
}

Not Found
{
  "errorType": "notFound",
  "errorMessage": "Not found",
  "errorDetails": null
}

Unprocessable Entity
{
  "errorType": "unknownError",
  "errorMessage": "Unknown error",
  "errorDetails": null
}

Too Many Requests
{
  "errorType": "tooManyRequests",
  "errorMessage": "Too many requests",
  "errorDetails": null
}

Internal Server Error
{
  "errorType": "internalServerError",
  "errorMessage": "Internal Server Error",
  "errorDetails": null
}

Create order

Usage of return URLs​

HTTP request​

Request​

Header parameters​

Body parameters​

Response​

Response params​

Error response​

Error response parameters​

Error codes​