Create order

POST /v1/orders

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.
kado / skrill_crypto	These providers don't use the returnSuccessUrl and returnFailedUrl URLs.

HTTP request

https://fiat-api.changelly.com/v1/orders

Request

Request

Header parameters

Name	Type	Required	Description
X-Api-Key	string	true	Your public API key.
X-Api-Signature	string	true	The query's serialized body signed by your private key according to the RSA-SHA256 method.

Body parameters

Name	Type	Required	Description
externalOrderId	string	false	Order ID provided by you.
externalUserId	string	true	User ID provided by you.
providerCode	string	true	The On-Ramp provider code. Possible values.
currencyFrom	string	true	Ticker of the pay-in currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
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.
ip	string	false	User's IP address.
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).
paymentMethod	string	false	The payment method code. Possible values.
userAgent	string	false	User Agent.
metadata	object	false	Metadata object, which can contain any parameters you need.
returnSuccessUrl	string	false	Return URL after a successfully completed transaction.
returnFailedUrl	string	false	Return URL after a failed transaction.

Learn more details about the returnSuccessUrl and returnFailedUrl parameters in the section.

Payload

application/json

{
  "externalOrderId": "71ahw34",
  "externalUserId": "122hd",
  "providerCode": "moonpay",
  "currencyFrom": "USD",
  "currencyTo": "ETH",
  "amountFrom": "150",
  "country": "EE",
  "walletAddress": "0x8cfbd31371e9bec8c82ae101e25bd9394c03a227",
  "paymentMethod": "card",
  "returnSuccessUrl": "https://example.com/success",
  "returnFailedUrl": "https://example.com/failed",
}

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": "71ahw34",
  "externalUserId": "122hd",
  "providerCode": "moonpay",
  "currencyFrom": "USD",
  "currencyTo": "ETH",
  "amountFrom": "150",
  "country": "EE",
  "walletAddress": "0x8cfbd31371e9bec8c82ae101e25bd9394c03a227",
  "paymentMethod": "card"
}'

Response

Sample response

note

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

application/json

{
  "redirectUrl": "https://buy.moonpay.com/?CurrencyCode=eth&baseCurrencyCode=usd&currencyCode=eth&baseCurrencyAmount=150&externalTransactionId=71ahw34&walletAddress=0x8cfbd31371e9bec8c82ae101e25bd9394c03a227",
  "returnSuccessUrl": "https://example.com/success",
  "returnFailedUrl": "https://example.com/failed",
  "orderId": "5154302e-3stl-75p4",
  "externalUserId": "122hd",
  "externalOrderId": "71ahw34",
  "providerCode": "moonpay",
  "currencyFrom": "USD",
  "currencyTo": "ETH",
  "amountFrom": "150",
  "country": "EE",
  "state": null,
  "ip": null,
  "walletAddress": "0x8cfbd31371e9bec8c82ae101e25bd9394c03a227",
  "walletExtraId": null,
  "paymentMethod": "card",
  "userAgent": null,
  "metadata": null,
  "createdAt": "2019-07-22T10:10:09.000"
}

Response params

Name	Type	Required	Description
redirectUrl	string	true	URL to the provider's purchase page.
returnSuccessUrl	string	false	Return URL after a successfully completed transaction.
returnFailedUrl	string	false	Return URL after a failed transaction.
orderId	string	true	Internal order ID provided by Fiat API.
externalUserId	string	true	User ID provided by you.
externalOrderId	string	true	Order ID provided by you.
providerCode	string	true	The On-Ramp provider code. Possible values.
currencyFrom	string	true	Ticker of the pay-in currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
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.
ip	string	true	User's IP address.
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).
paymentMethod	string	true	The payment method code. Possible values.
userAgent	string	true	User Agent.
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.
createdAt	date-time	true	Time in ISO 8601 format.

Learn more details about the returnSuccessUrl and returnFailedUrl parameters in the section.

Error schema

Name	Type	Required	Description
errorType	string	true	Error type.
errorMessage	string	true	Error message.
errorDetails	array of objects	true	If the error contains no details, errorDetails equals null.

Possible error types:

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

errorDetails item schema

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

Error codes

Code	Message
400	BadRequest
401	Unauthorized
429	TooManyRequests
500	InternalServerError

400

BadRequest

{
  "errorType": "limits",
  "errorMessage": "Limits error",
  "errorDetails": [
    {
      "cause": "min",
      "value": "20"
    }
  ]
}

401

Unauthorized

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

429

TooManyRequests

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

500

InternalServerError

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