Hosted Mode Integration

Hosted mode gives you full control over the user experience. Users stay on your platform throughout the entire flow.

Overview

Hosted mode allows you to integrate Rampnow’s on-ramp and off-ramp services while maintaining complete control over the user interface. Unlike widget integration, users never leave your platform — you control the entire experience, with Rampnow handling only the payment steps when needed.

Seamless Experience

Keep users on your platform throughout the entire flow

Custom Branding

Minimal Rampnow branding, maximum control

Full UI Control

Build your own interface using Rampnow’s REST APIs

Implementation Steps

Onboard User (optional)

This step is optional. Create Order (next step) accepts the same user object and onboards the customer automatically. Call Create Customer User up front only if you want to pre-register a customer or fetch their KYC status via the returned uid before creating an order.

Use the Create Customer User endpoint. It returns a customer uid you can use with Get Customer KYC.

cURL

curl --request POST \
  --url https://api.rampnow.io/api/partner/v1/ext/customer_user \
  --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 '{
    "userDetail": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+491234567890",
      "dateOfBirth": "1990-01-15",
      "gender": "male",
      "country": "DE",
      "address": {
        "line1": "123 Main St",
        "city": "Berlin",
        "postalCode": "10115",
        "country": "DE"
      }
    }
  }'

Key fields

Field	Required	Description
`userDetail.firstName` / `lastName`	Required	User’s name
`userDetail.email`	Required	User’s email address
`userDetail.phone`	Required	Phone number with country code
`userDetail.dateOfBirth`	Required	Date of birth in `YYYY-MM-DD` format
`userDetail.gender`	Required	`male`, `female` or `unknown`
`userDetail.country`	Required	ISO 3166-1 alpha-2 country code (e.g. `DE`, `US`)
`userDetail.address`	Optional	User’s residential address

Create Order

Create an order using the Create Hosted Order endpoint. The response includes a redirectUrl — send the user there to complete payment (and any KYC) on Rampnow’s hosted screens.

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",
    "user": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+491234567890",
      "dateOfBirth": "1990-01-15",
      "gender": "male",
      "country": "DE"
    },
    "wallet": {
      "address": "0xUserDestinationWalletAddress",
      "custodyType": "unhosted"
    }
  }'

Key fields

Field	Required	Description
`orderType`	Required	`buy` (onramp) or `sell` (offramp)
`externalOrderUid`	Required	Your unique order id — used later to look the order up
`srcCurrency` / `srcChain`	Required	What the user pays with. For an onramp: fiat currency (e.g. `EUR`) on chain `fiat`
`srcAmount`	Required	Amount in `srcCurrency`
`dstCurrency` / `dstChain`	Optional	Crypto asset + network to deliver (e.g. `ETH` on `ethereum`)
`user`	Required	Customer details — `firstName`, `lastName`, `email`, `phone`, `dateOfBirth`, `gender`, `country`
`wallet`	Optional	Destination wallet `{ address, custodyType }` (`custodyType`: `unhosted` or `hosted`)

The response returns orderUid, userUid and a redirectUrl. Redirect the user to redirectUrl; track the outcome via webhooks (below) or by polling the order (see Track order status).

Set Up Webhooks (Optional)

Track transaction status in real-time by configuring webhooks in your Rampnow Partner Dashboard.

Webhook setup documentation is available in our Webhook Guide.

Integration Flow

Support & Config Endpoints

Instead of probing asset_config pair-by-pair, use these bulk endpoints to discover what is live:

Endpoint	Returns
`GET /api/partner/v1/ext/ramp_order/config`	Full support matrix in one call: every configured asset, payment mode and order type, split by direction (`buy` = onramp, `sell` = offramp).
`GET /api/partner/v1/ext/ramp_order/blocked_currencies`	Supported countries with the crypto currencies blocked in each. Pass `?country=<ISO alpha-2>` to filter to one country.

Both are HMAC-authenticated like the rest of the external API.

Partner Fee (Markup)

To take a margin on an order, pass your fee on the quote and order-creation requests. Both fields are optional and override the fee configured on your account for that request:

Field	Type	Description
`partnerPctFee`	number	Partner fee as a percentage of the order amount (e.g. `1.5` = 1.5%)
`partnerFixedFee`	number	Fixed partner fee in the order’s base currency

They apply to the quote (/ext/ramp_order/quote) and the checkout order (/ext/ramp_order/checkout). When omitted, the account-configured partner fee applies. The resolved partner amount is returned as a separate partner entry in feeDetails on the order responses — GET /ext/ramp_order/{uid} and the webhook — so you can reconcile it (see below). It is not broken out in the quote, where it stays folded into the platform line. Add either field to the Create Order body from the previous step, e.g.:

{
  "orderType": "buy",
  "externalOrderUid": "your-unique-order-id",
  "srcCurrency": "EUR",
  "srcChain": "fiat",
  "srcAmount": "250",
  "dstCurrency": "ETH",
  "dstChain": "ethereum",
  "user": { "firstName": "John", "lastName": "Doe", "email": "[email protected]", "phone": "+491234567890", "dateOfBirth": "1990-01-15", "gender": "male", "country": "DE" },
  "wallet": { "address": "0xUserDestinationWalletAddress", "custodyType": "unhosted" },
  "partnerPctFee": 1.5
}

Fee Breakdown (`feeDetails`)

Quote and order responses return a feeDetails array. Each entry has a type, fee, currency, and isInclusive. The returned type values are:

`type`	Description	Where
`platform`	Aggregated platform fee (Rampnow service + processing, and — in the quote — your partner fee)	quote + order
`network`	Blockchain network (gas) fee	quote + order
`partner`	Your partner fee / markup, broken out as its own line	order only (`GET /ext/ramp_order/{uid}` + webhook)

Reconciliation. In the quote, the partner fee is folded into platform, so total = platform + network. On the order responses it is broken out: platform excludes the partner amount and a partner line is added, so total = platform + network + partner — the total is identical either way.

Track order status

You receive a webhook on every order status change (recommended — see Webhooks). To poll instead, use Get Order:

cURL

curl --request GET \
  --url https://api.rampnow.io/api/partner/v1/ext/ramp_order/your-unique-order-id \
  --header 'X-RAMPNOW-API-KEY: YOUR_API_KEY' \
  --header 'X-RAMPNOW-TIMESTAMP: UNIX_SECONDS' \
  --header 'X-RAMPNOW-SIGN: HMAC_SHA256_SIGNATURE'

The path parameter is your externalOrderUid (the id you sent on Create Order), not Rampnow’s orderUid.
The response is an array — orderList — of orders matching that external id (normally one). Read status (and paymentStatus) from the entry; the full list of statuses and their meaning is in the webhook status table.

When to Use Hosted Mode

Ideal For

Platforms requiring a fully custom user experience
Teams wanting minimal Rampnow branding
Applications needing full UI control over every step

Considerations

Requires custom UI development on your end
Integration takes longer than widget mode or the SDK
You manage the user flow and error handling

Next Steps

Create Customer User

Onboard users with the Create Customer User endpoint

Create Order

Create hosted orders via the API

Webhooks

Set up real-time transaction status notifications

Rampnow SDK

Prefer a quicker integration? Try the SDK with built-in event handling

Learn about Rampnow

Resources

Onramp

Offramp

Overview

Seamless Experience

Custom Branding

Full UI Control

Implementation Steps

Key fields

Key fields

Integration Flow

Support & Config Endpoints

Partner Fee (Markup)

Fee Breakdown (`feeDetails`)

Track order status

When to Use Hosted Mode

Next Steps

Create Customer User

Create Order

Webhooks

Rampnow SDK

​Overview

Seamless Experience

Custom Branding

Full UI Control

​Implementation Steps

​Key fields

​Key fields

​Integration Flow

​Support & Config Endpoints

​Partner Fee (Markup)

​Fee Breakdown (feeDetails)

​Track order status

​When to Use Hosted Mode

​Next Steps

Create Customer User

Create Order

Webhooks

Rampnow SDK

Overview

Implementation Steps

Key fields

Key fields

Integration Flow

Support & Config Endpoints

Partner Fee (Markup)

Fee Breakdown (`feeDetails`)

Track order status

When to Use Hosted Mode

Next Steps