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

# On-Ramp integration

> Step-by-step walkthrough to convert fiat into crypto with the Ramps API, using either a single on-ramp order or a reusable on-ramp session.

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.

<Note>
  Available payment methods depend on the country. See [Countries & payment methods](/ramps-api/overview/countries/overview) first.
</Note>

## Two ways to run an on-ramp

|                            | On-Ramp order                                      | On-Ramp session                                                                                          |
| -------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **What it is**             | A single purchase tied to one quote (locked rate). | A reusable deposit account (e.g. a CVU/CLABE) tied to a destination crypto address.                      |
| **How orders are created** | You create the order explicitly.                   | Orders are created **automatically** each time the customer sends fiat to the session's deposit account. |
| **Rate**                   | The quote you pass.                                | The market rate at the moment of each deposit.                                                           |
| **Best for**               | One-off purchases with a confirmed amount.         | Recurring top-ups where the customer sends fiat whenever they want.                                      |

Both share the same setup (customer and KYC).

## Common setup

<Steps>
  <Step title="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](/ramps-api/authentication/acquire-access-token)
  </Step>

  <Step title="Create the customer">
    Register the end user as a customer. You'll use the returned `customerId` throughout the flow.

    → [Create Customer](/ramps-api/customers/create-customer)
  </Step>

  <Step title="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.

    → [Terms & Conditions](/ramps-api/terms-and-conditions/introduction) · [Accept Terms](/ramps-api/customers/accept-terms)
  </Step>

  <Step title="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)](/ramps-api/kyc/overview)
  </Step>

  <Step title="Provision the deposit account (when required)">
    Some countries and payment methods require the fiat **deposit account** to exist before operating (for example, a CLABE in Mexico). Create it and wait until it becomes `ENABLED` — you'll receive an `ACCOUNT.ENABLED` webhook when it's ready. For methods that generate the deposit instructions on the fly, you can skip this step.

    → [Create Deposit Account](/ramps-api/customers/create-deposit-account) · [Account Events](/ramps-api/webhooks/account-events)
  </Step>
</Steps>

## Option 1 — Single on-ramp order

<Steps>
  <Step title="Create a quote">
    Request an on-ramp quote (fiat → crypto), specifying amount and payment method. The quote holds a price for a limited time and returns a `quoteId`.

    → [Create Quote](/ramps-api/quotes/create-quote)
  </Step>

  <Step title="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).

    → [Create On-Ramp Order](/ramps-api/on-ramp/create-on-ramp-order)
  </Step>

  <Step title="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](/ramps-api/webhooks/on-ramp-events) (recommended) or by polling [List On-Ramp Orders](/ramps-api/on-ramp/list-on-ramp-orders).
  </Step>
</Steps>

## Option 2 — On-ramp session

<Steps>
  <Step title="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](/ramps-api/on-ramp/create-on-ramp-session)
  </Step>

  <Step title="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](/ramps-api/webhooks/on-ramp-events) or by inspecting the session via [Retrieve an On-Ramp Session](/ramps-api/on-ramp/retrieve-an-on-ramp-session).
  </Step>
</Steps>

## Order lifecycle

| Status       | Meaning                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `PENDING`    | Order created, waiting for the fiat payment.                                                               |
| `PROCESSING` | Payment detected, trade in progress.                                                                       |
| `COMPLETED`  | Crypto delivered to the destination address.                                                               |
| `CANCELLED`  | Something went wrong with the order and it needs review. It can be resolved through customer support (CX). |
| `REFUNDED`   | The amount was refunded to the customer.                                                                   |

## Testing in sandbox

In sandbox there's no real fiat movement. Use the deposit simulation endpoint to move an order forward as if the user had paid.

→ [Simulate Deposit for On-Ramp (Sandbox)](/ramps-api/sandbox/simulate-deposit-for-on-ramp-sandbox)