Skip to main content
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 and KYC 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

Flexible KYC

Use KYC Share or let Rampnow handle verification

​
Implementation Steps

1

Onboard User

Onboard your user to Rampnow through the KYC Share API. If KYC share is not used, Rampnow will initiate a KYC process during the transaction.
Before calling this API, Sumsub KYC share setup must be completed with Rampnow if you want to use the KYC share feature. Contact [email protected] for setup details.
Use the Create Customer User endpoint to onboard retail users:
cURL
curl --request POST \
  --url https://api.rampnow.io/api/partner/v1/ext/customer_user \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "kycShareReq": {
      "token": "<sumsub_share_token>"
    },
    "userDetail": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "dateOfBirth": "1990-01-15",
      "country": "DE",
      "address": {
        "line1": "123 Main St",
        "city": "Berlin",
        "postalCode": "10115",
        "country": "DE"
      }
    }
  }'

​
Key Fields

FieldRequiredDescription
kycShareReq.tokenOptionalSumsub KYC share token. Omit if Rampnow handles KYC.
userDetail.firstNameRequiredUser’s first name
userDetail.lastNameRequiredUser’s last name
userDetail.emailRequiredUser’s email address
userDetail.countryRequiredISO 3166-1 alpha-2 country code (e.g. DE, US)
userDetail.dateOfBirthRequiredDate of birth in YYYY-MM-DD format
userDetail.phoneOptionalPhone number with country code
userDetail.addressOptionalUser’s residential address
2

Create Order

Once onboarded, create an order using the Create Hosted Order endpoint. The response contains all payment details to display on your UI.
cURL
curl --request POST \
  --url https://api.rampnow.io/api/partner/v1/ext/checkout/order \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{
    "orderType": "buy",
    "srcCurrency": "EUR",
    "srcAmount": "250",
    "dstCurrency": "ETH",
    "dstChain": "ethereum",
    "walletAddress": "0xYourWalletAddress"
  }'
The API response will include the order ID, payment instructions, and transaction details that you can render in your custom UI.
3

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

​
When to Use Hosted Mode

  • Platforms requiring a fully custom user experience
  • Teams wanting minimal Rampnow branding
  • Applications needing full UI control over every step
  • 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

KYC Share API

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