> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rampnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Mode Integration

> Complete control over user experience with minimal Rampnow branding

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

## 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.

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Seamless Experience" icon="sparkles">
    Keep users on your platform throughout the entire flow
  </Card>

  <Card title="Custom Branding" icon="palette">
    Minimal Rampnow branding, maximum control
  </Card>

  <Card title="Full UI Control" icon="sliders">
    Build your own interface using Rampnow's REST APIs
  </Card>
</div>

***

## Implementation Steps

<Steps>
  <Step title="Onboard User">
    Onboard your user to Rampnow through the **Create Customer User API**.

    Use the [Create Customer User](/api-reference/createcustomeruser) endpoint to onboard retail users:

    ```bash cURL theme={null}
    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": "john@example.com",
          "phone": "+1234567890",
          "dateOfBirth": "1990-01-15",
          "country": "DE",
          "address": {
            "line1": "123 Main St",
            "city": "Berlin",
            "postalCode": "10115",
            "country": "DE"
          }
        }
      }'
    ```

    ### Key Fields

    | Field                    | Required | Description                                       |
    | ------------------------ | -------- | ------------------------------------------------- |
    | `userDetail.firstName`   | Required | User's first name                                 |
    | `userDetail.lastName`    | Required | User's last name                                  |
    | `userDetail.email`       | Required | User's email address                              |
    | `userDetail.country`     | Required | ISO 3166-1 alpha-2 country code (e.g. `DE`, `US`) |
    | `userDetail.dateOfBirth` | Required | Date of birth in `YYYY-MM-DD` format              |
    | `userDetail.phone`       | Optional | Phone number with country code                    |
    | `userDetail.address`     | Optional | User's residential address                        |
  </Step>

  <Step title="Create Order">
    Once onboarded, create an order using the [Create Hosted Order](/api-reference/createcheckoutorder) endpoint. The response contains all payment details to display on your UI.

    ```bash cURL theme={null}
    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.
  </Step>

  <Step title="Set Up Webhooks (Optional)">
    Track transaction status in real-time by configuring webhooks in your **Rampnow Partner Dashboard**.

    <Tip>
      Webhook setup documentation is available in our [Webhook Guide](/api-reference/webhook).
    </Tip>
  </Step>
</Steps>

***

## Integration Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Partner as Your Platform
    participant Rampnow as Rampnow API

    User->>Partner: Initiates buy/sell
    Partner->>Rampnow: Create Customer User
    Rampnow-->>Partner: User onboarded
    Partner->>Rampnow: Create Hosted Order
    Rampnow-->>Partner: Order + payment details
    Partner->>User: Display payment instructions
    User->>Partner: Completes payment
    Rampnow-->>Partner: Webhook notification (order status)
    Partner->>User: Confirm transaction
```

***

## When to Use Hosted Mode

<AccordionGroup>
  <Accordion title="Ideal For" icon="check">
    * Platforms requiring a fully custom user experience
    * Teams wanting minimal Rampnow branding
    * Applications needing full UI control over every step
  </Accordion>

  <Accordion title="Considerations" icon="triangle-exclamation">
    * Requires custom UI development on your end
    * Integration takes longer than widget mode or the SDK
    * You manage the user flow and error handling
  </Accordion>
</AccordionGroup>

***

## Next Steps

<div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '1rem'}}>
  <Card title="Create Customer User" icon="user-check" href="/api-reference/createcustomeruser">
    Onboard users with the Create Customer User endpoint
  </Card>

  <Card title="Create Order" icon="cart-shopping" href="/api-reference/createcheckoutorder">
    Create hosted orders via the API
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhook">
    Set up real-time transaction status notifications
  </Card>

  <Card title="Rampnow SDK" icon="cube" href="/api-reference/sdk">
    Prefer a quicker integration? Try the SDK with built-in event handling
  </Card>
</div>