This is the core call of the Intent flow. It creates the order and the customer, and returns the hosted checkout link.
Create Order is not idempotent. Rampnow doesn’t de-duplicate on
externalOrderUid, so sending the same request twice creates two orders. If the call times out or returns a 5xx, call Get Order with your externalOrderUid first, and retry only if orderList is empty.Request
Call Create Checkout Order. Buy and sell orders use the same endpoint;orderType, the currency pair and the wallet object differ.
- Onramp (buy)
- Offramp (sell)
cURL
curl --request POST \
--url https://api.rampnow.io/api/partner/v1/ext/ramp_order/checkout \
--header 'Content-Type: application/json' \
--header 'X-RAMPNOW-API-KEY: YOUR_API_KEY' \
--header 'X-RAMPNOW-TIMESTAMP: UNIX_SECONDS' \
--header 'X-RAMPNOW-SIGN: HMAC_SHA256_SIGNATURE' \
--data '{
"orderType": "buy",
"externalOrderUid": "your-unique-order-id",
"srcCurrency": "EUR",
"srcChain": "fiat",
"srcAmount": "250",
"dstCurrency": "ETH",
"dstChain": "ethereum",
"returnUrl": "https://your-app.com/orders/your-unique-order-id",
"user": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"phone": "+491234567890",
"dateOfBirth": "1990-01-15",
"gender": "male",
"country": "DE"
},
"wallet": {
"crytpoAccountDetail": {
"address": "0xUserDestinationWalletAddress",
"custodyType": "unhosted"
}
}
}'
Order fields
| Field | Required | Description |
|---|---|---|
orderType | Required | buy for onramp |
externalOrderUid | Required | Your unique order id, used to look the order up later. Not de-duplicated: a repeated call creates another order |
srcCurrency / srcChain | Required | Fiat currency the user pays with (e.g. EUR) on chain fiat |
srcAmount / dstAmount | One of | Set either the source or destination amount, not both |
dstCurrency / dstChain | Optional | Crypto asset + network to deliver (e.g. ETH on ethereum). Send both or neither; required when you send wallet |
user | Required | Customer details (see below) |
wallet.crytpoAccountDetail | Optional | The user’s destination crypto wallet { address, custodyType } (custodyType: unhosted or hosted). Note the field name keeps the crytpo spelling. If you omit wallet, the crypto goes to your partner wallet, and the user can’t enter one at checkout. |
addressTag | Optional | Memo/tag for chains that need one (XRP, XLM, TON, …) |
paymentMode | Optional | Preferred payment method. If omitted, the user picks one during checkout |
returnUrl | Optional | Where Rampnow sends the user after checkout. Rampnow appends ?status=<payment status>; include your own order id in the URL. |
webhookUrl | Optional | Not currently used for delivery: webhooks always go to the account-level URL set in API Hub. Leave it unset |
partnerPctFee / partnerFixedFee | Optional | Per-order partner fee override. See Partner fee |
cURL
curl --request POST \
--url https://api.rampnow.io/api/partner/v1/ext/ramp_order/checkout \
--header 'Content-Type: application/json' \
--header 'X-RAMPNOW-API-KEY: YOUR_API_KEY' \
--header 'X-RAMPNOW-TIMESTAMP: UNIX_SECONDS' \
--header 'X-RAMPNOW-SIGN: HMAC_SHA256_SIGNATURE' \
--data '{
"orderType": "sell",
"externalOrderUid": "your-unique-order-id",
"srcCurrency": "USDT",
"srcChain": "ethereum",
"srcAmount": "500",
"dstCurrency": "EUR",
"dstChain": "fiat",
"returnUrl": "https://your-app.com/orders/your-unique-order-id",
"user": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"phone": "+491234567890",
"dateOfBirth": "1990-01-15",
"gender": "male",
"country": "DE"
},
"wallet": {
"bankAccountDetail": {
"name": "John Doe",
"iban": "DE89370400440532013000",
"bic": "COBADEFFXXX",
"country": "DE",
"currency": "EUR"
}
}
}'
Order fields
| Field | Required | Description |
|---|---|---|
orderType | Required | sell for offramp |
externalOrderUid | Required | Your unique order id, used to look the order up later. Not de-duplicated: a repeated call creates another order |
srcCurrency / srcChain | Required | Crypto asset + network the user sells (e.g. USDT on ethereum) |
srcAmount / dstAmount | One of | Set either the source or destination amount, not both |
dstCurrency / dstChain | Optional | Fiat payout currency (e.g. EUR) on chain fiat. Send both or neither; required when you send wallet |
user | Required | Customer details (see below) |
wallet.bankAccountDetail | Optional | Payout bank account: name, iban or accountNumber, bic, bankName, country, currency, … Required fields vary by payout currency (e.g. taxId + IFSC in bic for INR). If you omit wallet, the payout goes to your partner account. |
paymentMode | Optional | Preferred payment method. If omitted, the user picks one during checkout |
returnUrl | Optional | Where Rampnow sends the user after checkout. Rampnow appends ?status=<payment status>; include your own order id in the URL. |
webhookUrl | Optional | Not currently used for delivery: webhooks always go to the account-level URL set in API Hub. Leave it unset |
partnerPctFee / partnerFixedFee | Optional | Per-order partner fee override. See Partner fee |
User details
There is no separate user-creation call. Rampnow creates the customer from the
user object on the order, or matches an existing customer by email, and returns their userUid in the response.user field | Required | Description |
|---|---|---|
firstName / lastName | Required | Customer’s legal name |
email | Required | Customer’s email. Used to match returning customers |
phone | Required | Phone number with country code (e.g. +491234567890) |
dateOfBirth | Required | Date of birth in YYYY-MM-DD format |
gender | Required | male, female or unknown |
country | Required | ISO 3166-1 alpha-2 country code (e.g. DE) |
address | Optional | Residential address (line1, city, postalCode, country, …) |
Response
The response is the same for buy and sell orders:{
"code": 0,
"message": "success",
"traceId": "trace-id",
"data": {
"orderUid": "rampnow-order-uid",
"userUid": "rampnow-user-uid",
"redirectUrl": "https://app.rampnow.io/..."
}
}
| Field | Description |
|---|---|
orderUid | Rampnow’s order id. Also included in webhooks for this order |
userUid | Rampnow’s customer id: existing, or newly created from user |
redirectUrl | Hosted checkout URL. Send the user here next |
Next: Redirect the user
Send the user to the hosted checkout