> For the complete documentation index, see [llms.txt](https://docs.pay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pay.io/api-reference/user-payment-api/create-onramp-url/add-on-ramping-to-your-site.md).

# Add On-Ramping To Your Site

This guide gives an overview on how to implement the On-Ramping functionality using Pay.io's Payment Gateway and User Payment API. \
\
Learn more about the feature and benefits in [On-Ramping: Buying Crypto with Fiat](/on-ramping-buying-crypto-with-fiat.md).

{% hint style="info" %}
**API endpoint used in this guide  ->** [`POST /v1/user/onramp/get_url`](/api-reference/user-payment-api/create-onramp-url.md)
{% endhint %}

## Integration Flow

The integration relies on a **single** **backend** **API** **call** to generate a unique **URL**, which is then rendered on your frontend within an iframe.

```mermaid
sequenceDiagram
    participant User as End User
    participant Frontend as Merchant Cashier UI
    participant Backend as Merchant Backend
    participant PayIO as Pay.io API
    participant Provider as Onramp Provider (MELD)

    User->>Frontend: Clicks "Buy Crypto" button
    Frontend->>Backend: Request onramp session
    Backend->>PayIO: POST /v1/user/onramp/get_url
    PayIO-->>Backend: Returns secure URL (link)
    Backend-->>Frontend: Passes URL to UI
    Frontend->>Frontend: Renders URL inside iFrame
    User->>Provider: Completes KYC & buys crypto via Fiat
    Provider-->>PayIO: Executes crypto transfer to user wallet
    PayIO-->>Frontend: Balance updated (Standard Deposit)
```

## **Generate the On Ramp URL (Backend)**

To initiate the flow, your backend must call the Pay.io User Payments API to generate a unique, user-specific URL.

**Endpoint**: [`POST /v1/user/onramp/get_url`](/api-reference/user-payment-api/create-onramp-url.md)

**Authentication**: API Key (`Bearer YOUR_API_KEY` in the header)

{% code title="Request payload example" %}

```json
{
  "provider": "MELD",
  "currency_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_reference_id": "player_98765",
  "country": "GB",
  "operation": "deposit",
  "site": "yourcasino.io",
  "theme": "dark"
}
```

{% endcode %}

**Key Parameters**

* `provider`: Currently supports only the provider `"MELD"`.
* `country`: The user's ISO 3166-1 alpha-2 country code (e.g., `GB`, `DE`). This dictates which payment methods (like Apple Pay) are displayed.
* `theme`: Choose `"dark"` or `"light"` to match your Cashier UI design.

{% code title="Response example" %}

```json
{
  "success": true,
  "data": {
    "link": "https://widget.onramp-provider.com/?session=abc123xyz..."
  }
}
```

{% endcode %}

## **Render the iframe (Frontend)**

Once your backend receives the `link` from the API, pass it to your frontend. You will need to embed this URL seamlessly into your Cashier UI, so the user does not feel like they are leaving your site.

{% hint style="info" %}
**Best Practices**

* Ensure the iframe width is 100% of its container, especially for mobile users.
* Give the iframe a sufficient minimum height (e.g., `600px` to `700px`) to prevent awkward inner scrolling during the KYC steps.
* Remove default borders to make the widget look native to your platform.
  {% endhint %}

{% code title="Example for frontend HTML for the Iframe" %}

```html
<div class="onramp-widget-container">
  <iframe 
    src="YOUR_GENERATED_URL_HERE" 
    title="Buy Crypto Securely"
    allow="camera; microphone; payment" 
    frameborder="0">
  </iframe>
</div>

<style>
  .onramp-widget-container {
    width: 100%;
    max-width: 500px; /* Adjust based on your UI */
    margin: 0 auto;
    border-radius: 12px;
    overflow: hidden;
  }
  .onramp-widget-container iframe {
    width: 100%;
    height: 700px;
    border: none;
  }
</style>
```

{% endcode %}

{% hint style="info" %}
The `allow="camera; microphone"` attributes are crucial, as users may need their device camera to upload ID documents for the **KYC** **verification** **step**.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pay.io/api-reference/user-payment-api/create-onramp-url/add-on-ramping-to-your-site.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.