Returning to your app

You give Ripio a single redirect URL during onboarding, and it is configured on your account. It must be publicly reachable and can be any route under your domain:

https://partner-fintech.com/ramps/success

Whichever flow the user took, the widget sends them back to that one URL. What differs is whether transaction parameters are appended to it.

In the screenshots below the button reads “Volver a Ripio” because the account they were taken from is named Ripio. On your account it carries your own brand name — see Partner settings.

Which screens append parameters

Final screen the user reaches	Reached when	Redirect	Parameters
Transfer instructions (Argentina CVU, Mexico CLABE, Colombia BRE-B key)	the user confirms the order	on button press	full set
Off-ramp deposit screen	your account shows the QR deposit screen	on button press	full set
Off-ramp, no deposit screen	your account skips the QR deposit screen	automatic	full set
Order confirmed	Brazil PIX, Colombia Nequi request-to-pay, and every payment-gateway flow (Mercado Pago, PSE, Bancolombia request-to-pay, card)	on button press	none — the bare URL

If you operate in Brazil, or through Mercado Pago, PSE, Bancolombia or Nequi, do not build your post-purchase experience on the callback query string: those flows end on a screen that redirects without parameters. Use On-Ramp Events keyed by external_ref instead, which is the authoritative record for every flow.

In a gateway flow the user does return from the provider carrying the provider’s own parameters, but that return lands on Ripio, not on you: Ripio consumes it, re-enters the widget on the confirmed screen, and the parameters do not survive that hop.

On Ramp

On the flows that append parameters, the user lands on a final screen with a “Back to Partner” button. Pressing it sends them to your URL with the transaction details in the query string. Example final URL:

https://partner-fintech.com/ramps/success?external_ref=123e4567-e89b-42d3-a456-426614174000&action=onramp&crypto_amount=700.21146386&token=UXD&network=ETHEREUM_SEPOLIA&deposit_address=0x646eE511616A20a321A1cB72DADCB04C0485b97e&fiat_amount=100000&fiat_currency=ARS&fees=1000&payment_method=bank_transfer&session_id=1234&country_code=AR&ramp=Ripio&apiVersion=V2

Query Parameters:

Parameter	Description
`external_ref`	The `external_ref` you used to mint the session token — the UUID identifying this user in your system.
`action`	Operation type, always `onramp` in this case.
`crypto_amount`	Amount of cryptocurrency the user received.
`token`	Cryptocurrency selected by the user (e.g., `UXD`).
`network`	Blockchain network used for the crypto transfer.
`deposit_address`	User’s wallet address where crypto was sent.
`fiat_amount`	Amount of fiat used in the transaction.
`fiat_currency`	Fiat currency used by the user (e.g., `ARS`).
`fees`	Total fees applied to the transaction (e.g., platform, network, etc.).
`payment_method`	Normalized payment method. Always `bank_transfer` today — see Payment method values. Omitted when the order has no payment method recorded.
`session_id`	Optional session identifier if sent using `_tracking_session`.
`country_code`	Country code based on the user’s location (e.g., `AR`).
`ramp`	Always `Ripio`.
`apiVersion`	Contract version of this redirect. Always `V2`.

Note: The session_id parameter will only be included if the partner specified a _tracking_session when constructing the On Ramp widget URL.

Payment method values

Today payment_method is always bank_transfer. The only screens that append parameters are the transfer-instruction ones, and every method that reaches them — Argentina CVU, Mexico CLABE, Colombia BRE-B key — is a bank-transfer variant. The off-ramp sends bank_transfer as well.

Other values become reachable if the remaining flows start appending parameters too. Do not treat this parameter as the record of how the user paid: the authoritative source is paymentMethodType on the On-Ramp Events payload, which is populated for every flow.

Example image of the final On Ramp screen:

Transfer instructions screen with the button back to the partner

Off Ramp

Which of the two forms below you get is decided by whether the QR deposit screen is enabled on your account, not by your integration.

Automatic redirection

When the QR deposit screen is not enabled, the widget redirects the user to your URL as soon as the Off Ramp flow is confirmed, with the transaction details appended as query parameters. The user never sees a deposit screen inside the widget, so you are expected to move the crypto on their behalf.

https://partner-fintech.com/ramps/success?external_ref=123e4567-e89b-42d3-a456-426614174000&action=offramp&crypto_amount=20&token=UXD&network=ETHEREUM_SEPOLIA&deposit_address=0x76E0cCB0EBE289C6502F97EC8458cf2337a1d339&payment_method=bank_transfer&fiat_amount=25000&fiat_currency=ARS&session_id=tracking-id-example&country_code=AR&ramp=Ripio&apiVersion=V2

Query Parameters:

Parameter	Description
`external_ref`	The `external_ref` you used to mint the session token — the UUID identifying this user in your system.
`action`	Operation type, always `offramp` in this case.
`crypto_amount`	Amount of cryptocurrency being sold.
`token`	Selected cryptocurrency (e.g., `UXD`).
`network`	Selected blockchain network (e.g., `ETHEREUM`, `ETHEREUM_SEPOLIA`).
`deposit_address`	Deposit address where the crypto must be sent.
`payment_method`	Payout method. Always `bank_transfer` on the off-ramp.
`fiat_amount`	Amount of fiat the user will receive.
`fiat_currency`	Fiat currency the user will receive (e.g., `ARS`).
`session_id`	Optional session identifier if provided using `_tracking_session`.
`country_code`	Country code based on the user’s location (e.g., `AR`).
`ramp`	Always `Ripio`.
`apiVersion`	Contract version of this redirect. Always `V2`.

Note: The session_id parameter will only be present if the partner includes a _tracking_session value when generating the Off Ramp widget URL. This allows the partner to maintain traceability between their internal user session and the transaction on Ripio’s side.

Manual redirection

When it is enabled, the widget displays a final screen with the deposit details, and a QR code, so the user can send the cryptocurrency themselves from whichever wallet they prefer. In this case:

The user will see the deposit address (deposit_address) and the network (network) details.
The user must send the specified amount manually from their wallet.
Once the funds are received, Ripio will process the transaction and deposit the corresponding fiat amount in the user’s bank account.

Additionally, this screen will display a “Back to Partner” button. If the user clicks this button, they will be redirected to the same redirection URL configured by the partner, with the full transaction details included in the query string—just as in the automatic redirection flow. This ensures that even in manual flows, the partner can receive the complete transaction context and allow users to return to their platform seamlessly. Example image of the final Off Ramp screen (manual flow):

Overview

Widget integration

API Integration

Which screens append parameters

On Ramp

Payment method values

Off Ramp

Automatic redirection

Manual redirection

​Which screens append parameters

​On Ramp

​Payment method values

​Off Ramp

​Automatic redirection

​Manual redirection

Which screens append parameters

On Ramp

Payment method values

Off Ramp

Automatic redirection

Manual redirection