Create a headless onramp order
curl --request POST \
--url https://api-sb.meld.io/crypto/order/headless/onramp \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"countryCode": "US",
"destinationCurrencyCode": "USDC",
"destinationWalletAddress": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProvider": "NOAH",
"sourceAmount": 200,
"sourceCurrencyCode": "USD"
}
'import requests
url = "https://api-sb.meld.io/crypto/order/headless/onramp"
payload = {
"countryCode": "US",
"destinationCurrencyCode": "USDC",
"destinationWalletAddress": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProvider": "NOAH",
"sourceAmount": 200,
"sourceCurrencyCode": "USD"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
countryCode: 'US',
destinationCurrencyCode: 'USDC',
destinationWalletAddress: '<string>',
paymentMethodType: 'CREDIT_DEBIT_CARD',
serviceProvider: 'NOAH',
sourceAmount: 200,
sourceCurrencyCode: 'USD'
})
};
fetch('https://api-sb.meld.io/crypto/order/headless/onramp', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sb.meld.io/crypto/order/headless/onramp",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'countryCode' => 'US',
'destinationCurrencyCode' => 'USDC',
'destinationWalletAddress' => '<string>',
'paymentMethodType' => 'CREDIT_DEBIT_CARD',
'serviceProvider' => 'NOAH',
'sourceAmount' => 200,
'sourceCurrencyCode' => 'USD'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sb.meld.io/crypto/order/headless/onramp"
payload := strings.NewReader("{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sb.meld.io/crypto/order/headless/onramp")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sb.meld.io/crypto/order/headless/onramp")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"customerId": "<string>",
"externalCustomerId": "<string>",
"externalOrderId": "<string>",
"id": "<string>",
"payload": {
"countryCode": "<string>",
"customerId": "<string>",
"customerPhoneNumber": "<string>",
"destinationCurrencyCode": "<string>",
"destinationWalletAddress": "<string>",
"externalCustomerId": "<string>",
"externalOrderId": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"providerData": {
"serviceProvider": "<string>",
"subaccountCustomerId": "<string>",
"externalSubaccountCustomerId": "<string>"
},
"redirectUrl": "<string>",
"serviceProvider": "NOAH",
"sourceAmount": 123,
"sourceCurrencyCode": "<string>"
},
"paymentMethodResponseDetails": {
"sessionToken": "<string>",
"merchantTransactionId": "<string>"
},
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProviderDetails": {}
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}Headless
Create a headless onramp order
Creates a headless onramp order. Caller passes customer + provider + payment method and receives a method-specific payload in paymentMethodResponseDetails:
- ACH/SEPA/PIX → bank-transfer details to display.
- CREDIT_DEBIT_CARD → a provider-hosted widget, or
NativeSdkOrderwhen renderMode=SDK_NATIVE. - STRIPE + CREDIT_DEBIT_CARD/APPLE_PAY → one
NativeSdkOrdershape;paymentMethodTypeselects the method.destinationNetworkCodeandX-Idempotency-Keyare required. Stripe remains disabled until rollout gates clear. - MERCURYO + APPLE_PAY → native (non-widget) flow: a
sessionToken(JWT) +merchantTransactionId. No redirect URL. The caller renders the Apple Pay sheet itself (Safari/WebView via ApplePaySession) and drives these endpoints, authenticated with headerX-Crypto-Session-Token: <sessionToken>: ononvalidatemerchantcall POST /crypto/session/mercuryo/apple-pay/validate-merchant with the event’s validationURL; ononpaymentauthorizedcall POST /crypto/session/mercuryo/apple-pay/process with the Apple payToken + themerchantTransactionIdfrom this response. The Mercuryo buy_token is fetched and stored server-side, so the caller never handles it. If native Apple Pay is unavailable for the route the call fails with INVALID_PAYMENT_METHOD (no redirect fallback).
POST
/
crypto
/
order
/
headless
/
onramp
Create a headless onramp order
curl --request POST \
--url https://api-sb.meld.io/crypto/order/headless/onramp \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"countryCode": "US",
"destinationCurrencyCode": "USDC",
"destinationWalletAddress": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProvider": "NOAH",
"sourceAmount": 200,
"sourceCurrencyCode": "USD"
}
'import requests
url = "https://api-sb.meld.io/crypto/order/headless/onramp"
payload = {
"countryCode": "US",
"destinationCurrencyCode": "USDC",
"destinationWalletAddress": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProvider": "NOAH",
"sourceAmount": 200,
"sourceCurrencyCode": "USD"
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
countryCode: 'US',
destinationCurrencyCode: 'USDC',
destinationWalletAddress: '<string>',
paymentMethodType: 'CREDIT_DEBIT_CARD',
serviceProvider: 'NOAH',
sourceAmount: 200,
sourceCurrencyCode: 'USD'
})
};
fetch('https://api-sb.meld.io/crypto/order/headless/onramp', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sb.meld.io/crypto/order/headless/onramp",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'countryCode' => 'US',
'destinationCurrencyCode' => 'USDC',
'destinationWalletAddress' => '<string>',
'paymentMethodType' => 'CREDIT_DEBIT_CARD',
'serviceProvider' => 'NOAH',
'sourceAmount' => 200,
'sourceCurrencyCode' => 'USD'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sb.meld.io/crypto/order/headless/onramp"
payload := strings.NewReader("{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sb.meld.io/crypto/order/headless/onramp")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sb.meld.io/crypto/order/headless/onramp")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"countryCode\": \"US\",\n \"destinationCurrencyCode\": \"USDC\",\n \"destinationWalletAddress\": \"<string>\",\n \"paymentMethodType\": \"CREDIT_DEBIT_CARD\",\n \"serviceProvider\": \"NOAH\",\n \"sourceAmount\": 200,\n \"sourceCurrencyCode\": \"USD\"\n}"
response = http.request(request)
puts response.read_body{
"customerId": "<string>",
"externalCustomerId": "<string>",
"externalOrderId": "<string>",
"id": "<string>",
"payload": {
"countryCode": "<string>",
"customerId": "<string>",
"customerPhoneNumber": "<string>",
"destinationCurrencyCode": "<string>",
"destinationWalletAddress": "<string>",
"externalCustomerId": "<string>",
"externalOrderId": "<string>",
"paymentMethodType": "CREDIT_DEBIT_CARD",
"providerData": {
"serviceProvider": "<string>",
"subaccountCustomerId": "<string>",
"externalSubaccountCustomerId": "<string>"
},
"redirectUrl": "<string>",
"serviceProvider": "NOAH",
"sourceAmount": 123,
"sourceCurrencyCode": "<string>"
},
"paymentMethodResponseDetails": {
"sessionToken": "<string>",
"merchantTransactionId": "<string>"
},
"paymentMethodType": "CREDIT_DEBIT_CARD",
"serviceProviderDetails": {}
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}{
"code": "<string>",
"errors": [
"<string>"
],
"message": "<string>",
"requestId": "<string>",
"serviceProviderDetails": {
"code": "5034",
"message": "Digital currency and blockchain combination is restricted for customer's country"
},
"timestamp": "2026-08-14T09:41:22.482+00:00"
}Authorizations
Headers
Dated API version to use for this request, e.g. 2026-02-03.
Example:
"2026-02-03"
Body
application/json
Request to create a headless onramp order
Country code (ISO 3166-1 alpha-2)
Minimum string length:
1Example:
"US"
Destination cryptocurrency code
Minimum string length:
1Example:
"USDC"
Wallet address to receive the cryptocurrency
Minimum string length:
1Payment method type
Available options:
CREDIT_DEBIT_CARD, APPLE_PAY, ACH, SEPA, PIX, MOBILE_MONEY Service provider to use for the order
Available options:
NOAH, DUENETWORK, BRALE, YELLOWCARD, MERCURYO Example:
"NOAH"
Source amount
Required range:
x >= 0Example:
200
Source currency code (ISO 4217)
Minimum string length:
1Example:
"USD"
The end-user's IP address. Required by some service providers.
Meld customer id (one of customerId / externalCustomerId is required)
Customer phone number — required for MOBILE_MONEY
Caller's external customer id (one of customerId / externalCustomerId is required)
Caller's reference for the order; unique per account when provided
Provider-specific extension; subtype keyed by serviceProvider
Show child attributes
Show child attributes
Redirect URL — required for CARD/REDIRECT flows
Response
Headless order created
Headless onramp order response envelope
Meld customer id
Caller's external customer id
Caller's external order id
Unique order ID for tracking the onramp order
Echo of the integrator's request payload for this order
Show child attributes
Show child attributes
Method-specific response payload
- ApplePayOrder
- BankTransferOrder
- CardOrder
Show child attributes
Show child attributes
Payment method type for this order
Available options:
CREDIT_DEBIT_CARD, APPLE_PAY, ACH, SEPA, PIX, MOBILE_MONEY Raw provider receiving-bank details (untyped passthrough). Present for bank-transfer methods when the provider returns them; carries fields that have no typed home on paymentMethodResponseDetails (e.g. beneficiary/company name, bank name, address). Omitted when empty.
Show child attributes
Show child attributes