Launch the widget

Once you have a session token, you launch the widget by sending the user from your platform to a Ripio URL with the token in the _to query parameter. There is nothing to install and no script to embed — the widget is a hosted page. The on-ramp and the off-ramp are separate entry points.

Environment	On-ramp	Off-ramp
Production	`https://b2b-widget-onramp.ripio.com?_to=<authentication_token>`	`https://b2b-widget-onramp.ripio.com/offramp.html?_to=<authentication_token>`
Sandbox	`https://b2b-widget-onramp.sandbox.ripio.com?_to=<authentication_token>`	`https://b2b-widget-onramp.sandbox.ripio.com/offramp.html?_to=<authentication_token>`

Example:

https://b2b-widget-onramp.ripio.com?_to=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uIjoiMThhYjZkNmM4ZDk4NWE5Y2M4N2IwMTcyN2ExMWYwOTQ4YzJmNGUxYzQ0ODEzZTZhNDU0MzcxYTg1NzY3YjE5OSIsImV4cCI6MTcwODI5ODMzM30.4aRUEXLkUs3jf-DYMcH8claUuDKfc8qbTjW6JzpBTjI

Both entry points open on the same first screen: the user is asked for their email address, which is where sign-in begins. See Sign-in and terms.

Query parameters

Every parameter below is optional. They prefill or constrain the flow so the user has less to type.

Parameter	Type	Description
`_addr`	string (Optional)	Wallet address to prefill for the on-ramp. When set, the field is not editable. Ex: `0x646eE511616A20a321A1cB72DADCB04C0485b97e`
`_net`	string (Optional)	Preselect the blockchain network. It must match the networks available to your account. Ex: `ETHEREUM`
`_amount`	string (Optional)	Prefill the fiat amount. Ex: `1000` or `4321.35`
`_crypto`	string (Optional)	Preselect the cryptocurrency, which then is not editable. It must match the cryptos available to your account. Ex: `USDT`
`_la`	string (Optional)	Force the interface language, overriding the one derived from your account country. One of `es`, `es-rp`, `en`, `br`. See Partner settings.
`_tracking_session`	string (Optional)	Custom identifier to track the user session on your end. It will be returned in the webhooks under `metadata.session`. Ex: `random-tracking-id-onramp`

_addr is a prefill for users who have no address on file, not an override. If the end user already has a wallet address stored with Ripio, that address wins and the field is read-only. Sending a different _addr for a returning user has no effect.

The destination screen with a prefilled, non-editable wallet address

Prefills are cached for the lifetime of the session token, so a user who reloads the page mid-flow keeps them. Passing the same token again with different values will not reset a flow already in progress.

Tracking session parameter

The _tracking_session parameter can be used as follow:

https://b2b-widget-onramp.sandbox.ripio.com/index.html?_to=<token>&_tracking_session=random-tracking-id-onramp

Then, you will receive the tracking session in the webhooks as follows:

{
  "eventType": "ON-RAMP.DEPOSIT.RECEIVED",
  "transactionObject": {
    ...
    "metadata": {
      "session": "random-tracking-id-onramp"
    }
  }
}

It is also echoed back to you on the redirect as session_id — see Returning to your app.

Reserved parameters

You will see three more parameters in your logs. Ripio generates them, and you should not construct them yourself.

Parameter	Generated by	Purpose
`order_status=pending`	Ripio, as the return URL handed to payment gateways	Brings the user back into the widget on the order-confirmed screen after they pay at their bank or card provider.
`kyc=pending`	Ripio, as the return URL handed to the identity provider	Brings the user back into the widget on the verification-status screen. See Identity verification.
`_at`	Ripio, inside the payout-rejected email	Opens the widget directly in the recovery flow for a rejected off-ramp payout. See Recovering a rejected payout.

_at travels in the URL fragment (#_at=…), not the query string, so the token never reaches server logs or a Referer header. If your edge, WAF or analytics layer rewrites or strips URL fragments on links your users open, the recovery link will not work.

Overview

Widget integration

API Integration

Widget URLs

Query parameters

Tracking session parameter

Reserved parameters

Next steps

Returning to your app

User flows

​Widget URLs

​Query parameters

​Tracking session parameter

​Reserved parameters

​Next steps

Returning to your app

User flows

Widget URLs

Query parameters

Tracking session parameter

Reserved parameters

Next steps