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

# Create On-Ramp Order

> Initiates a fiat-to-crypto on-ramp transaction process based on a previously obtained quote. Returns transaction details and fiat payment instructions for the customer.



## OpenAPI

````yaml ramps-api/openapi.json POST /api/v1/onramp/
openapi: 3.1.0
info:
  title: Ripio Ramp API
  version: v1
  description: >-
    API for Ripio ramp services, enabling partners to integrate On-Ramp,
    Off-Ramp, customer management, KYC processes, and other financial
    functionalities. This API is RESTful, uses JSON for requests and responses,
    and standard HTTP status codes. This document is based on the
    'onramp-api.pdf' provided and aims to be compliant with OpenAPI
    Specification v3.1.0. The PDF indicates that the API documentation is a
    draft and subject to change.
servers:
  - url: https://skala-sandbox.ripio.com
    description: Sandbox environment
  - url: https://skala.ripio.com
    description: Production environment
security:
  - BearerToken: []
tags:
  - name: Authentication
    description: Operations related to API authentication and authorization.
  - name: Support Tickets
    description: >-
      Operations for raising and tracking customer support tickets with Ripio's
      support team. This feature must be enabled for your account by the Ripio
      team.
  - name: Customers
    description: Operations related to customer management.
  - name: KYC
    description: Operations related to Know Your Customer processes.
  - name: Investor Profile
    description: >-
      Brazilian accounts only: the investor-profile (suitability) questionnaire
      required by Resolução BCB nº 520/2025.
  - name: Fiat Accounts
    description: Operations related to managing fiat accounts and their requirements.
  - name: Quotes
    description: Operations related to obtaining and managing conversion quotes.
  - name: On-Ramp
    description: Operations related to fiat-to-crypto (on-ramp) processes.
  - name: Off-Ramp
    description: Operations related to crypto-to-fiat (off-ramp) processes.
  - name: Refunds
    description: >-
      Operations for returning the money of an on-ramp or off-ramp operation
      that could not be completed. Each ramp must be enabled for your account by
      the Ripio team.
  - name: Transactions
    description: Operations related to listing and managing all transaction types.
  - name: Networks
    description: >-
      Operations related to retrieving available deposit and withdrawal
      networks.
  - name: Rates
    description: Operations related to retrieving market rates.
  - name: Transaction Limits
    description: >-
      Operations related to retrieving per-transaction limits by currency and
      ramp operation.
  - name: Sandbox
    description: Operations specific to the sandbox environment for testing purposes.
  - name: Webhooks
    description: Webhook event notifications from Ripio Ramp API.
  - name: Sell and Pay
    description: >-
      Endpoints for managing Sell and Pay transactions, which allow customers to
      convert cryptocurrency to fiat currency and pay merchants via QR codes
paths:
  /api/v1/onramp/:
    post:
      tags:
        - On-Ramp
      summary: Create On-Ramp Order
      description: >-
        Initiates a fiat-to-crypto on-ramp transaction process based on a
        previously obtained quote. Returns transaction details and fiat payment
        instructions for the customer.
      operationId: createOnRampOrder
      parameters:
        - $ref: '#/components/parameters/EndUserIp'
        - $ref: '#/components/parameters/EndUserAgent'
        - $ref: '#/components/parameters/EndUserDeviceId'
      requestBody:
        required: true
        description: Details for creating an on-ramp order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnRampOrderCreationRequest'
      responses:
        '201':
          description: On-Ramp order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnRampOrderResponse'
        '400':
          description: >-
            Bad Request - the order was not created. There are four distinct
            causes, told apart by the `code` field of the response body. **Two
            of them are about the deposit account and need opposite reactions**,
            so branch on the code rather than on the status:


            - **`40019` `FiatAccountNotCreatedException`** - the customer has no
            fiat **deposit account** for this payment method. Retrying will
            never succeed: create the account with [Create Deposit
            Account](/ramps-api/customers/create-deposit-account) and wait until
            it is `enabled`. See which country and payment method combinations
            require it in the [On-Ramp integration
            guide](/ramps-api/guides/on-ramp-integration).

            - **`40014` `FiatAccountNotReadyException`** - the deposit account
            exists but is still `processing`: the payment provider has not
            registered its key yet. This one is transient - wait for the
            [`ACCOUNT.ENABLED`](/ramps-api/webhooks/account-events) webhook and
            create the order then.

            - **`20039` `TermsAndConditionsNotAcceptedException`** - the
            customer has not accepted the active Terms and Conditions. Nothing
            about the order is at fault: acceptance is per version, so this also
            hits a customer who accepted an earlier one. See [Terms and
            Conditions](/ramps-api/terms-and-conditions/introduction).

            - **Invalid payload** - e.g. an unknown `quoteId` or `customerId`, a
            malformed `depositAddress`, or a quote whose amount is too small
            once fees are applied. These come back as `20000` `ValidationError`
            with `detail` keyed by field name.


            A `400` on this endpoint always carries a body: read `code` and
            `type` before assuming the payload is at fault. A `20100` means the
            customer has no valid investor profile (Brazilian accounts only). A
            `20108` means Travel Rule requires a declaration of the counterparty
            and none was sent (Mexican accounts only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                fiatAccountNotCreated:
                  summary: Deposit account was never created - create it, do not retry
                  value:
                    code: 40019
                    type: FiatAccountNotCreatedException
                    detail:
                      message: >-
                        Customer does not have a fiat account for this payment
                        method. Create it with POST
                        /customers/{customerId}/fiatAccount/ and wait until it
                        is enabled before creating the order.
                    status: 400
                fiatAccountNotReady:
                  summary: Deposit account still processing - wait and retry
                  value:
                    code: 40014
                    type: FiatAccountNotReadyException
                    detail:
                      message: >-
                        Customer does not have a fiat account ready for the
                        on-ramp transaction.
                    status: 400
                unknownQuote:
                  summary: Quote does not exist
                  value:
                    code: 20000
                    type: ValidationError
                    detail:
                      quoteId:
                        - message: Quote does not exist.
                          code: invalid
                    status: 400
                termsNotAccepted:
                  summary: >-
                    The active Terms and Conditions have not been accepted
                    (20039)
                  description: >-
                    Terms and Conditions are versioned per country and only the
                    active version counts: a customer who accepted an earlier
                    version is refused here until they accept the current one.
                    Send them back through the acceptance flow — see [Terms and
                    Conditions](/ramps-api/terms-and-conditions/introduction).
                  value:
                    code: 20039
                    type: TermsAndConditionsNotAcceptedException
                    detail:
                      message: >-
                        Customer '3fa85f64-5717-4562-b3fc-2c963f66afa6' has not
                        accepted the current Terms and Conditions.
                    status: 400
                investorProfileRequired:
                  summary: 'Brazil: the customer has no valid investor profile (20100)'
                  description: >-
                    The customer never answered the investor questionnaire, or
                    their profile expired. Have them answer it with [Submit
                    Investor
                    Profile](/ramps-api/investor-profile/submit-investor-profile)
                    and retry. Only Brazilian accounts with the investor profile
                    enabled — see [Investor Profile
                    (Brazil)](/ramps-api/investor-profile/introduction).
                  value:
                    code: 20100
                    type: InvestorProfileRequiredException
                    detail:
                      message: >-
                        Customer '3fa85f64-5717-4562-b3fc-2c963f66afa6' does not
                        have a valid investor profile.
                    status: 400
                travelRuleRequired:
                  summary: 'Mexico: the counterparty has not been declared (20108)'
                  description: >-
                    Travel Rule is enforced for your account and this request
                    has no `travelRule`, with no current declaration to fall
                    back on — or the customer has a sale held for its
                    declaration, which blocks every new operation that does not
                    bring one. Ask the customer who owns the wallet, send
                    `travelRule` and retry. See [Travel Rule
                    (Mexico)](/ramps-api/travel-rule/introduction).
                  value:
                    code: 20108
                    type: TravelRuleRequiredException
                    detail:
                      message: >-
                        This operation requires a Travel Rule declaration: send
                        travelRule.
                    status: 400
                travelRuleInvalid:
                  summary: Malformed travelRule (20000)
                  description: >-
                    `fullName` and `country` are required when
                    `counterpartyIsSelf` is `false`, and `country` must be an
                    ISO-3166-1 alpha-2 code. The format is validated for every
                    account, even where Travel Rule does not apply.
                  value:
                    code: 20000
                    type: ValidationError
                    detail:
                      travelRule:
                        country:
                          - message: >-
                              'MEX' is not a valid country. Use the ISO-3166-1
                              alpha-2 code (e.g. MX).
                            code: invalid_choice
                    status: 400
        '401':
          description: Unauthorized - Invalid or missing access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40001
                type: NotAuthenticated
                detail:
                  message: Authentication credentials were not provided.
                  code: not_authenticated
                status: 401
        '404':
          description: >-
            Not Found - e.g., Customer not found or inactive, or Quote not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40004
                type: NotFound
                detail:
                  message: Not found.
                  code: not_found
                status: 404
components:
  parameters:
    EndUserIp:
      name: X-Ripio-User-Ip
      in: header
      required: false
      description: >-
        Optional. The public IP address of the **end user's device** (IPv4 or
        IPv6), captured on your frontend and forwarded by your backend — never
        your server's own address. Used for traceability and fraud prevention.
        An address that is not a valid IPv4 or IPv6 discards the end-user
        context of the request, without failing it. See [Forwarding end-user
        context](/ramps-api/guides/end-user-context).
      schema:
        type: string
        maxLength: 45
      example: 203.0.113.24
    EndUserAgent:
      name: X-Ripio-User-Agent
      in: header
      required: false
      description: >-
        Optional. The `User-Agent` of the **end user's browser or app**, not
        your backend's HTTP client. Longer values are truncated to 500
        characters. See [Forwarding end-user
        context](/ramps-api/guides/end-user-context).
      schema:
        type: string
        maxLength: 500
      example: >-
        Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)
        AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148
        Safari/604.1
    EndUserDeviceId:
      name: X-Ripio-User-Device-Id
      in: header
      required: false
      description: >-
        Optional. A stable identifier of the **end user's device**, as your app
        or frontend defines it. Longer values are truncated to 200 characters.
        See [Forwarding end-user context](/ramps-api/guides/end-user-context).
      schema:
        type: string
        maxLength: 200
      example: 8d3f2c1a-6b7e-4f9a-a1d2-3c4b5e6f7a8b
  schemas:
    OnRampOrderCreationRequest:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          description: Unique identifier for the customer.
          example: b6cecc1f-c90d-424b-adaa-c82b780696c1
        quoteId:
          type: string
          format: uuid
          description: Unique identifier for the quote obtained from the Quoting Endpoint.
          example: 8142b065-79c4-4f48-9e33-11b17bc658d4
        depositAddress:
          type: string
          description: The customer's deposit address on the chosen blockchain network.
          example: '0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32'
        externalRef:
          type: string
          format: uuid
          description: >-
            Unique identifier for the order that is being created, provided by
            the partner. **Must be a valid UUID** — arbitrary strings are
            rejected with a 400.
          example: e6c4f1ec-899f-43b5-8479-c2529e3f9c70
        extraData:
          type: object
          description: >-
            Additional data for the on-ramp order. Required for Colombia payment
            methods (`bank_transfer`, `r2p_bancolombia`, `r2p_nequi`).
          properties:
            callback:
              type: string
              format: uri
              description: >-
                Callback URL for payment notifications. Required for Colombia
                payment methods (`bank_transfer`, `r2p_bancolombia`,
                `r2p_nequi`).
              example: https://example.com/callback
            bankCode:
              type: string
              description: >-
                Bank code for Colombia `bank_transfer` payment method. Not
                required for `r2p_bancolombia` or `r2p_nequi`. Retrieve valid
                codes from `GET /api/v1/banks/`.
              example: '1001'
        travelRule:
          allOf:
            - $ref: '#/components/schemas/TravelRuleDeclarationRequest'
          description: >-
            Who owns `depositAddress`. **Mexico, from November 30, 2026:**
            required unless the customer already has a current declaration for
            that same `depositAddress`. See [Travel Rule
            (Mexico)](/ramps-api/travel-rule/introduction).
      required:
        - customerId
        - quoteId
        - depositAddress
        - externalRef
    OnRampOrderResponse:
      type: object
      properties:
        transaction:
          $ref: '#/components/schemas/OnRampTransactionDetail'
        fiatPaymentInstructions:
          type: object
          description: >-
            Instructions for the customer to complete the fiat deposit.
            Structure varies depending on payment method and currency:
            `bank_transfer` (Argentina) returns `cvu` and optionally `alias` (a
            human-readable identifier that can be used instead of the CVU for
            transfers — to enable alias customization, contact the Ripio team),
            `bank_transfer` (Mexico) returns `clabe`, `bank_transfer` (Colombia)
            returns `paymentUrl`, `breb` returns `brebKey`, `r2p_bancolombia`
            returns `paymentUrl`, `r2p_nequi` returns `phoneNumber`, `pix`
            (Brazil) returns `brCode`, `paymentUrl` and `expiresAt`. Methods
            backed by a persistent deposit account (`cvu`, `clabe`, `brebKey`)
            also include a `status` field (`processing`, `enabled` or
            `disabled`) indicating whether the deposit account is ready to
            operate; while `processing`, the deposit key/identifier may be
            `null`.


            `pix` has no reusable deposit account: payment instructions are
            generated per order, so they carry no `status` and are only returned
            by Create On-Ramp Order (not by an On-Ramp Session). `brCode` is a
            dynamic, single-use PIX BR Code EMV ("copia e cola") for exactly
            this order: it carries no PIX key, the amount is fixed to the quote,
            only the CPF/CNPJ from the customer's approved KYC can pay it, and
            it must never be cached or reused. `paymentUrl` is a hosted payment
            page, and `expiresAt` is when both stop being payable — after it,
            create a new order.
          additionalProperties: true
          examples:
            - cvu: '0100000000000000000001'
              alias: juan.perez.ramp
              status: enabled
            - cvu: '0100000000000000000001'
              status: enabled
            - clabe: '706180196550550550'
              status: enabled
            - paymentUrl: https://example.com/payment/abc123
            - brebKey: '@ABC123'
              status: enabled
            - phoneNumber: '*****1234'
            - brCode: >-
                00020101021226650014br.gov.bcb.pix2543pix.example.com/v2/invoice/57301741758054405204000053039865802BR5912Example
                Ltda6009Sao Paulo62280524invoice/573017417580544063041D78
              paymentUrl: https://payments.sandbox.example.com/abc123
              expiresAt: '2024-04-10T19:17:07.702533Z'
      required:
        - transaction
        - fiatPaymentInstructions
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: Application-specific error code.
        type:
          type: string
          description: Type of error or exception.
        detail:
          type:
            - object
            - array
          description: >-
            Error details. The shape depends on the error:


            - Most business errors return an object with a `message` key.

            - Field validation errors return an object keyed by field name, each
            holding an array of `{ message, code }`.

            - Request-level validation errors (e.g. a missing query parameter)
            return a bare array of `{ message, code }`.
          properties:
            message:
              type: string
              description: Detailed error message.
          additionalProperties: true
        status:
          type: integer
          description: HTTP status code.
      required:
        - code
        - type
        - detail
        - status
    TravelRuleDeclarationRequest:
      type: object
      description: >-
        The customer's declaration of the **counterparty** of the operation,
        required by the Mexican Travel Rule: the owner of the destination wallet
        on an on-ramp, the owner of the source wallet on an off-ramp. Ripio
        checks the format only, not whether it is true. See [Travel Rule
        (Mexico)](/ramps-api/travel-rule/introduction).
      properties:
        counterpartyIsSelf:
          type: boolean
          description: >-
            `true` when the wallet belongs to the customer: name and country are
            then taken from their KYC, and `fullName` and `country` are not
            stored — but they are still validated if sent, so leave them out.
            `false` when it belongs to someone else: send both fields.
          example: false
        fullName:
          type: string
          maxLength: 255
          description: >-
            Full name of the wallet's owner, as the customer declares it: a
            person or a company, in one field. Required when
            `counterpartyIsSelf` is `false`.
          example: María Pérez López
        country:
          type: string
          description: >-
            Country of residence of the wallet's owner, as an ISO-3166-1 alpha-2
            code. Required when `counterpartyIsSelf` is `false`.
            Case-insensitive and trimmed.
          example: MX
      required:
        - counterpartyIsSelf
    OnRampTransactionDetail:
      description: Details of an on-ramp transaction.
      allOf:
        - $ref: '#/components/schemas/OnRampTransaction'
        - type: object
          properties:
            travelRule:
              allOf:
                - $ref: '#/components/schemas/TravelRuleDeclaration'
              description: >-
                Mexico: the current Travel Rule declaration. Returned by the
                create endpoints and by the per-ramp retrieve endpoints; **not**
                by Retrieve an Order (`GET /api/v1/transactions/{orderId}/`),
                list endpoints or the `transactions` of a session.
    OnRampTransaction:
      type: object
      description: Details of an on-ramp transaction.
      properties:
        transactionId:
          type: string
          format: uuid
          description: Unique identifier for the on-ramp transaction.
          example: 21d8a046-3221-4b43-a301-0f9adcdd9a45
        createdAt:
          type: string
          format: date-time
          description: Date and time the on-ramp transaction was created.
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
        quoteId:
          type: string
          format: uuid
          description: Reference to the original quote used for this transaction.
        fromCurrency:
          type: string
          description: The source currency (fiat) used in the on-ramp transaction.
          example: ARS
        toCurrency:
          type: string
          description: The target cryptocurrency received in the on-ramp transaction.
          example: USDC
        amount:
          type: string
          description: >-
            The amount of the target cryptocurrency received (based on the
            original quote).
        chain:
          type: string
          description: The target blockchain network for the cryptocurrency deposit.
          example: ETHEREUM_SEPOLIA
        metadata:
          type: object
          description: Additional metadata associated with the transaction.
          additionalProperties: true
          example: {}
        txnHash:
          type:
            - string
            - 'null'
          description: >-
            Transaction hash of the on-chain withdrawal to the customer's
            `depositAddress`. `null` until the crypto has been sent, and
            populated once it has.
          example: null
        paymentMethodType:
          type: string
          description: The payment method used for the fiat deposit.
          example: bank_transfer
        depositAddress:
          type: string
          description: The customer's deposit address on the target blockchain.
        source:
          type: string
          description: Indicates the origin of the on-ramp order.
          enum:
            - ON_RAMP
            - ON_RAMP_SESSION
          example: ON_RAMP
        sender:
          type:
            - string
            - 'null'
          description: >-
            Name of the holder of the originating fiat account (e.g. CVU/CLABE
            owner). Null when not provided by the fiat provider.
          example: Juan Pérez
        status:
          type: string
          description: Current state of the on-ramp order.
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - CANCELLED
            - REFUNDED
          example: COMPLETED
        refundable:
          type: boolean
          description: >-
            Whether a [fiat refund](/ramps-api/refunds/request-fiat-refund) can
            be requested for this order right now. Computed per request, so use
            it to decide whether to call the refund endpoint instead of
            discovering it through a 400.
          example: false
        refundDestinationRequired:
          type:
            - boolean
            - 'null'
          description: >-
            Whether requesting a refund for this order requires naming a
            destination `fiatAccountId`. `false` means the money is returned to
            the account the customer paid from and a `fiatAccountId` is
            rejected. `null` when the order is not in refund territory.
          example: false
        latestRefund:
          anyOf:
            - $ref: '#/components/schemas/LatestFiatRefund'
            - type: 'null'
          description: >-
            State of the most recent refund of this order's deposit, or `null`
            if there never was one. The only place a rejected refund request is
            visible.
      required:
        - transactionId
        - createdAt
        - customerId
        - quoteId
        - fromCurrency
        - toCurrency
        - amount
        - chain
        - paymentMethodType
        - depositAddress
        - source
    TravelRuleDeclaration:
      type:
        - object
        - 'null'
      description: >-
        The **current** declaration for the operation's key — the wallet on an
        on-ramp, the session or the order on an off-ramp — or `null` when there
        is none. It is what covers the next operations, not necessarily the one
        in force when an older order was processed. When `counterpartyIsSelf` is
        `true`, `fullName` and `country` are `null`: the customer's own KYC data
        is used. See [Travel Rule
        (Mexico)](/ramps-api/travel-rule/introduction).
      properties:
        counterpartyIsSelf:
          type: boolean
          example: false
        fullName:
          type:
            - string
            - 'null'
          example: María Pérez López
        country:
          type:
            - string
            - 'null'
          example: MX
      required:
        - counterpartyIsSelf
        - fullName
        - country
    LatestFiatRefund:
      type: object
      description: >-
        State of the most recent refund of the order's deposit. The refund is
        not necessarily one you requested — Ripio may return a deposit on its
        own after a failed order — so read `initiatedBy` before presenting it as
        the customer's own request.
      properties:
        refundId:
          type: string
          format: uuid
          description: Unique identifier of the refund.
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - REJECTED
            - FAILED
            - CANCELLED
          description: >-
            Current state of the refund: `PENDING` (registered, not yet sent to
            the provider), `PROCESSING` (sent, awaiting confirmation),
            `COMPLETED` (the money reached its destination), `REJECTED` (the
            request was declined — see `rejectionReason` — and nothing was sent)
            or `FAILED` / `CANCELLED` (the attempt did not go through; contact
            Ripio support).
        rejectionReason:
          type: string
          enum:
            - ''
            - DUPLICATE_REQUEST
            - INVALID_DESTINATION
            - ALREADY_RESOLVED
            - NOT_ELIGIBLE
            - CONTACT_SUPPORT
          description: Why the request was declined. Empty unless `status` is `REJECTED`.
        initiatedBy:
          type: string
          enum:
            - PARTNER
            - WIDGET
            - SYSTEM
            - OPS
          description: >-
            Who originated the refund: `PARTNER` (your API call), `WIDGET` (the
            end user, from the widget), `SYSTEM` (returned automatically by
            Ripio) or `OPS` (registered by Ripio's support team on the
            customer's behalf).
        requestedAt:
          type: string
          format: date-time
          description: When the refund was requested.
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained via
        [/oauth2/token/](/ramps-api/authentication/acquire-access-token). Use as
        `Authorization: Bearer <access_token>`.

````

## Related topics

- [On-Ramp integration](https://docs.ripio.com/ramps-api/guides/on-ramp-integration.md)
- [Create On-Ramp Session](https://docs.ripio.com/ramps-api/on-ramp/create-on-ramp-session.md)
- [Simulate Deposit for On-Ramp (Sandbox)](https://docs.ripio.com/ramps-api/sandbox/simulate-deposit-for-on-ramp-sandbox.md)
- [Create Deposit Account](https://docs.ripio.com/ramps-api/customers/create-deposit-account.md)
- [Travel Rule (Mexico)](https://docs.ripio.com/ramps-api/travel-rule/introduction.md)


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