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.

API endpoint used in this guide -> Create a Payment Session

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.

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/payments

Authentication: API Key (Bearer YOUR_API_KEY in the header)

Request payload example

{
  "payment_type": "ON_RAMP",              // required
  "country": "GB",                        // required — ISO 3166-1 alpha-2
  "currency_id": "123e4567-e89b-12d3-a456-426614174000", // required
  "user_reference_id": "player_98765",    // required unless custom_wallet_address is set
  "custom_wallet_address": "0xabc123...", // optional — self-custody destination
  "amount": "100",                        // required for ON_RAMP
  "fiat_currency": "GBP",                 // required for ON_RAMP
  "redirect_url": "https://yourcasino.io/deposit-complete", // required
  "session_reference": "order_9981",      // optional
  "metadata": {}                          // optional
}

Key Parameters

• country - The user's ISO 3166-1 alpha-2 country code (e.g.GB,DE). Required, no default — dictates which payment methods (like Apple Pay) are displayed in the widget, and is locked into the widget once set.

• currency_id - UUID of the target cryptocurrency the user is buying. Must be a currency your merchant account has enabled with the provider.

• user_reference_id - Your platform's stable, unique player ID. Required unless custom_wallet_address is supplied — used to attribute the session to a system-custody wallet and is echoed back in webhooks as the customer identifier.

• custom_wallet_address - The user's own (self-custody) wallet address to receive funds instead of your platform's managed wallet. Optional. Only honoured if your merchant account has the custom-external-wallet flag enabled — otherwise the request is rejected with 403 custom_wallet_not_allowed_for_merchant. Contact your account manager to enable it.

• amount/fiat_currency - The fiat amount and 3-letter ISO 4217 currency the user is paying with. Both required for ON_RAMP and locked into the widget, so the user can't change them mid-flow.

• redirect_url - Where the widget sends the user after completing (or abandoning) the flow. Must start with http:// or https://.

• session_reference(optional) - Your own idempotency/tracking ID for this session. Echoed back in webhooks alongside correlation_key.

Response example

{
  "link": "https://onramp.example.com/session/abc123...",
  "correlation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479:order_9981",
  "expires_at": null
}

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.

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.

Example for frontend HTML for the Iframe

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

The allow="camera; microphone" attributes are crucial, as users may need their device camera to upload ID documents for the KYC verification step.