Skip to main content
On-Ramp lets your users buy crypto with fiat. There are two ways to run an on-ramp, and you can use either (or both) depending on your product. For request and response details, follow the endpoint link in each step.
Available payment methods depend on the country. See Countries & payment methods first.

​
Two ways to run an on-ramp

Both share the same setup (customer and KYC).

​
Common setup

1

Authenticate

Get an access token with the OAuth2 Client Credentials flow using your client_id and client_secret. Send it as a Bearer token on every subsequent call.→ Acquire Access Token
2

Create the customer

Register the end user as a customer. You’ll use the returned customerId throughout the flow.→ Create Customer
3

Accept Terms & Conditions

Right after creating the customer, register their acceptance of the active Terms & Conditions. This is a required step before the customer can operate.It is also a recurring one: acceptance covers the version that was shown, so a new version for the country blocks the customer again until they accept it. Re-check before operating instead of storing the result.→ Terms & Conditions · Accept Terms
4

Verify identity (KYC)

The customer must complete KYC before operating — the status must be COMPLETED. Choose the model that fits your integration (Ripio-hosted redirect or partner-submitted via API), and reuse an existing Ripio KYC via OTP when possible.→ Identity verification (KYC)
5

Brazilian accounts: collect the investor profile

If your account is in Brazil, your customers must answer a short suitability questionnaire after KYC and before their first order or session, and again every year. Check the status, show the questionnaire when it is REQUIRED or EXPIRED, and submit the answers; without it, creating an order, a session or a destination account fails with 20100. Accounts in other countries skip this step, whatever the customer’s nationality.→ Investor Profile (Brazil)
6

Provision the deposit account

The fiat deposit account is what the end user transfers to — a CVU in Argentina, a CLABE in Mexico, a BRE-B key in Colombia. Whether you must create it before the order depends on the country and the payment method: check Deposit account by country below. Brazil (PIX) has no deposit account at all — the order itself returns a payable BR Code.Where it is required, the deposit key is assigned asynchronously by the payment provider: the account starts as processing and becomes enabled once it can receive transfers. Subscribe to ACCOUNT.ENABLED instead of polling — the creation call answers 201 immediately, before the key exists.→ Create Deposit Account · Account Events

​
Deposit account by country

Creating the order before a required deposit account is ready returns HTTP 400 — not because of your payload. Two different codes, and they need opposite reactions:
  • 40019 FiatAccountNotCreatedException — the account was never created. Create it; retrying the order will never succeed on its own.
  • 40014 FiatAccountNotReadyException — it exists but is still processing. Wait for ACCOUNT.ENABLED and create the order then.
Always read the code field of the error body before looking for a mistake in your request.

​
Option 1 — Single on-ramp order

1

Create a quote

Request an on-ramp quote (fiat → crypto) with the customerId, specifying amount and payment method. The quote holds a price for a limited time and returns a quoteId. Quotes are scoped to a customer, so this step always comes after creating one.→ Create Quote
2

Create the on-ramp order

Create the order with the quoteId, the customerId, the destination depositAddress (crypto) and a partner externalRef. The response includes the fiat payment instructions (for example, the CVU/CLABE to transfer to, or a payment link).If the country and payment method require a deposit account, it must already be enabled by this point — otherwise the call returns 400, with code 40019 if the account was never created or 40014 if it is still processing. See Deposit account by country.→ Create On-Ramp Order
3

User pays and the order completes

The customer pays the fiat amount using the returned instructions. Once the deposit is detected and the trade executes, the order moves to COMPLETED and the crypto is sent to the destination address.Track it with On-Ramp Events (recommended) or by polling List On-Ramp Orders.

​
Option 2 — On-ramp session

1

Create the on-ramp session

Create a session for the customer with the destination crypto address, network and currency. The response includes a reusable fiat deposit account (e.g. a CVU) and its payment instructions. If the customer already has a session, it is reused/updated. The session does not expire.→ Create On-Ramp Session
2

User deposits fiat — orders are created automatically

The customer can send fiat to the session’s deposit account as many times as they want. Each deposit automatically creates an on-ramp order, converts the funds at the current rate and sends the crypto to the destination address. No per-deposit API call is needed.Track each order with On-Ramp Events or by inspecting the session via Retrieve an On-Ramp Session.

​
Order lifecycle

A cancelled order’s fiat can be returned to the customer — see Refunds.

​
Testing in sandbox

In sandbox there’s no real fiat movement. If your sandbox account is configured to skip KYC, you can go straight through the ramp flow. If KYC is enabled, complete the KYC step first and use the sandbox KYC simulation endpoints to approve or reject the submission. → KYC in sandbox Then use the deposit simulation endpoint to move an order forward as if the user had paid. → Simulate Deposit for On-Ramp (Sandbox)