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

# Buying crypto (on-ramp)

> The in-widget on-ramp flow by country and payment method: quote, payment instructions, PIX, request-to-pay, and where the user ends up.

The on-ramp turns the user's local currency into crypto delivered to a wallet address. The first half of the flow is the same everywhere; the second half depends on how they pay.

### The shared path

<Steps>
  <Step title="Choose an amount and a cryptocurrency">
    The widget quotes the operation and refreshes that quote on a timer, so the rate the user confirms is the rate they get. Minimums and maximums come from the [transaction limits](/ramps-api/transaction-limits/get-transaction-limits) that apply to your account.

    <img src="https://mintcdn.com/ripio-9dfd4837/08vkB56X36FZiua_/ramps-api/widget/assets/widget-onramp-quote.png?fit=max&auto=format&n=08vkB56X36FZiua_&q=85&s=7c51fd38e2a52cd22e4599f506022b11" alt="Amount entry showing the quote and the countdown to the next refresh" width="640" height="1126" data-path="ramps-api/widget/assets/widget-onramp-quote.png" />
  </Step>

  <Step title="Choose a network">
    Limited to the networks enabled for your account.
  </Step>

  <Step title="Confirm the destination address">
    Prefilled when you passed `_addr`, or when the user has an address on file. Otherwise they enter it.
  </Step>

  <Step title="Choose how to pay and confirm">
    Only the payment methods enabled for your account and country are offered. The confirmation screen breaks the cost down before the user commits.

    <img src="https://mintcdn.com/ripio-9dfd4837/08vkB56X36FZiua_/ramps-api/widget/assets/widget-onramp-checkout.png?fit=max&auto=format&n=08vkB56X36FZiua_&q=85&s=700ae8f498944e13a34ed669a3f6b578" alt="Confirmation screen with the full cost breakdown" width="630" height="1150" data-path="ramps-api/widget/assets/widget-onramp-checkout.png" />
  </Step>
</Steps>

### Where the flow goes from there

| Country and method | What the user sees | How they come back |
| - | - | - |
| Argentina CVU, Mexico CLABE, Colombia BRE-B key | A screen with the account details to transfer to, which they pay from their own bank | Button back to you, **with** transaction parameters |
| Brazil PIX | A PIX QR plus the *copia e cola* BR Code to copy, paid from their bank app | Confirmed screen, then the bare callback URL |
| Colombia Nequi request-to-pay | A push notification to approve in Nequi | Confirmed screen, then the bare callback URL |
| Argentina Mercado Pago, Colombia PSE and Bancolombia request-to-pay, card | They leave the widget for the provider's checkout | The provider returns them to Ripio, which re-enters the widget on the confirmed screen, then the bare callback URL |

<Warning>
  Only the transfer-instruction screens append transaction parameters to your redirect URL. For Brazil, Nequi and every gateway flow, build your post-purchase experience on [On-Ramp Events](/ramps-api/webhooks/on-ramp-events) keyed by `external_ref`. See [Returning to your app](/ramps-api/widget/get-started/returning-to-your-app).
</Warning>

<Note>
  In Brazil the BR Code is issued with the order itself, so there is nothing to wait for — but it **expires**. The widget shows the remaining time and the user has to start a new order once it runs out.
</Note>

### What your backend observes

The operation produces the ordinary on-ramp event chain, whichever way the user paid:

`ON-RAMP.DEPOSIT.RECEIVED` → `ON-RAMP.TRADE.COMPLETED` → `ON-RAMP.WITHDRAWAL.PROCESSING` → `ON-RAMP.WITHDRAWAL.COMPLETED`

If it fails instead, you get `ON-RAMP.ORDER.CANCELLED` with a `failureReason`, and the money is returned to the user — see [History and refunds](/ramps-api/widget/flows/history-and-refunds). Full payloads are in [On-Ramp Webhook Events](/ramps-api/webhooks/on-ramp-events).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.