> ## 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 Session
> Initiates an on-ramp session for a customer, specifying payment method, chain, cryptocurrency, and deposit address. Returns session details and payment instructions.
Each customer can only have one active on-ramp session at a time. If a session already exists for the customer, calling this endpoint will update it with the new parameters instead of creating a new one.
## OpenAPI
````yaml ramps-api/openapi.json POST /api/v1/onrampSession/
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: 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: 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/onrampSession/:
post:
tags:
- On-Ramp
summary: Create On-Ramp Session
description: >-
Initiates an on-ramp session for a customer, specifying payment method,
chain, cryptocurrency, and deposit address. Returns session details and
payment instructions.
operationId: createOnRampSession
requestBody:
required: true
description: Details for creating an on-ramp session.
content:
application/json:
schema:
$ref: '#/components/schemas/OnRampSessionCreationRequest'
examples:
Sandbox:
summary: Sandbox (RTEST on Ethereum Sepolia)
value:
customerId: fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1
paymentMethodType: bank_transfer
chain: ETHEREUM_SEPOLIA
currency: RTEST
depositAddress: '0x866B933Aabc4F9813405C6E393dbD4B600eF3E2e'
responses:
'201':
description: On-Ramp session created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OnRampSessionResponse'
'400':
description: >-
Bad Request - e.g., invalid parameters, or user already has an
active session.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'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.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 40004
type: NotFound
detail:
message: Not found.
code: not_found
status: 404
components:
schemas:
OnRampSessionCreationRequest:
type: object
properties:
customerId:
type: string
format: uuid
description: Unique identifier for the customer.
example: fca6d32f-2f7e-4f7e-b224-8be0b92fa3f1
paymentMethodType:
type: string
description: >-
The payment method used for the fiat deposit (e.g., `bank_transfer`,
`breb`). Note: `breb` is only available for Colombia.
example: bank_transfer
chain:
type: string
description: The blockchain network to be used for the conversion.
example: ETHEREUM_SEPOLIA
currency:
type: string
description: The target currency for the conversion.
example: USDC
depositAddress:
type: string
description: The customer's deposit address on the chosen blockchain network.
example: '0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32'
required:
- customerId
- paymentMethodType
- chain
- currency
- depositAddress
OnRampSessionResponse:
type: object
properties:
sessionId:
type: string
format: uuid
description: Unique identifier for the created on-ramp session.
customerId:
type: string
format: uuid
description: Unique identifier for the customer associated with the session.
createdAt:
type: string
format: date-time
description: Date and time the on-ramp session was created.
currency:
type: string
description: >-
The target crypto currency for every on-ramp transaction performed
with the created session.
chain:
type: string
description: The blockchain network to be used for the conversion.
depositAddress:
type: string
description: The customer's deposit address on the chosen blockchain network.
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`, `breb` (Colombia) returns
`brebKey`. 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`.
additionalProperties: true
examples:
- cvu: '0000465160000000070078'
alias: juan.perez.ramp
status: enabled
- cvu: '0000465160000000070078'
status: enabled
- clabe: '706180196550550550'
status: enabled
- brebKey: '@E6JZKEPG5S'
status: enabled
transactions:
type: array
description: >-
A list containing every transaction that has been either started or
completed through this session. On creation, will always be empty.
items:
$ref: '#/components/schemas/OnRampTransactionDetail'
required:
- sessionId
- customerId
- createdAt
- currency
- chain
- depositAddress
- fiatPaymentInstructions
- orders
ErrorResponse:
type: object
properties:
code:
type: integer
description: Application-specific error code.
type:
type: string
description: Type of error or exception.
detail:
type: object
properties:
message:
type: string
description: Detailed error message.
additionalProperties: true
status:
type: integer
description: HTTP status code.
required:
- code
- type
- detail
- status
OnRampTransactionDetail:
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 for the on-chain operation (null if not yet
processed).
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.
status:
type: string
description: The current transaction status.
enum:
- ON_RAMP_DEPOSIT_RECEIVED
- ON_RAMP_TRADE_COMPLETED
- ON_RAMP_WITHDRAWAL_PROCESSING
- ON_RAMP_WITHDRAWAL_COMPLETED
- ON_RAMP_TRADE_CANCELLED
- ON_RAMP_ORDER_EXPIRED
- ON_RAMP_REFUND_COMPLETED
example: WITHDRAWAL_PENDING
externalRef:
type: string
format: uuid
description: Unique identifier for the order provided by the partner.
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
required:
- transactionId
- createdAt
- customerId
- quoteId
- fromCurrency
- toCurrency
- amount
- chain
- paymentMethodType
- depositAddress
- status
- externalRef
- source
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 `.
````