> ## 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 Sell and Pay transaction
> Creates a new Sell and Pay transaction for converting cryptocurrency to fiat currency and paying a merchant via QR code. This endpoint automatically cancels any existing Sell and Pay transactions for the same customer. If all required fields are provided (customerId, externalRef, qrCode, paymentCurrency, depositCurrency, depositNetwork, and refundAddress), the transaction will be created with status PENDING. If any required fields are missing, the transaction will be created with status INCOMPLETE and must be completed using the update endpoint.
## Country support
| Country | `paymentCurrency` | Payment rail | Fiat account required |
| --------- | ----------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Argentina | `ARS` | QR | Yes — pre-create with `POST /sellAndPays/fiatAccounts/` |
| Colombia | `COP` | BREB-QR | No — calling `POST /sellAndPays/fiatAccounts/` for a Colombian customer returns `400 SellAndPayFiatAccountNotRequiredException` |
Both fixed-amount and open-amount QR codes are supported in every country. With an open-amount QR, the customer (or partner) provides the amount via the `update` endpoint before executing.
## Sandbox QR Codes — Argentina
For the sandbox environment, there are several QR codes available to simulate different transaction flows:
### valid-qr-code-with-amount
Use this QR code to simulate a successful payment flow with a random amount included in the QR code.
### valid-qr-code-without-amount
Use this QR code to simulate a successful payment flow where the amount is not included in the QR code and must be specified separately.
### invalid-qr-code
Use this QR code to simulate an error flow when scanning an invalid or malformed QR code.
### valid-qr-code-with-blocked-deposit
Use this QR code to simulate a scenario where the deposit destination is blocked or unavailable.
### valid-qr-code-with-slippage
Use this QR code to simulate a payment flow that experiences slippage, where the final amount differs from the expected amount.
## Sandbox QR Codes — Colombia (BREB-QR)
Use the strings below as the `qrCode` value in the sandbox environment:
### Fixed-amount QR (COP 100)
Use this QR code to simulate a successful BREB-QR payment with a fixed amount already encoded in the QR.
```text theme={null}
00020101021126320014CO.COM.CRB.LLA0410@CBI8UE7BZ49250014CO.COM.CRB.RED0103CRB5204000053031705406100.005802CO5909Ripio-PXT6006BOGOTA610611022185260014CO.COM.CRB.INC01040.0090430016CO.COM.CRB.TRXID0119P23e46ff8985de4a29091860014CO.COM.CRB.SEC01643c89cda78bcd348f723c55cd91cc9d65b9478378d2bed60accb5f09b0f361aa180290016CO.COM.CRB.CANAL0105ECOMM81250015CO.COM.CRB.CIVA01020382260014CO.COM.CRB.IVA01040.0083270015CO.COM.CRB.BASE01040.0084250015CO.COM.CRB.CINC01020363042617
```
### Open-amount QR
Use this QR code to simulate a successful BREB-QR payment without a pre-defined amount. The amount must be supplied via the [update](/ramps-api/sell-and-pay/update-sell-and-pay) endpoint before executing.
```text theme={null}
00020101021126320014CO.COM.CRB.LLA0410@CBI8UE7BZ49250014CO.COM.CRB.RED0103CRB5204000053031705802CO5909Ripio-PXT6006BOGOTA610611022185260014CO.COM.CRB.INC01040.0090430016CO.COM.CRB.TRXID0119P23e46ff8985de4a29091860014CO.COM.CRB.SEC01643c89cda78bcd348f723c55cd91cc9d65b9478378d2bed60accb5f09b0f361aa180290016CO.COM.CRB.CANAL0105ECOMM81250015CO.COM.CRB.CIVA01020382260014CO.COM.CRB.IVA01040.0083270015CO.COM.CRB.BASE01040.0084250015CO.COM.CRB.CINC01020363044E9E
```
## OpenAPI
````yaml ramps-api/openapi.json POST /api/v1/sellAndPays/
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/sellAndPays/:
post:
tags:
- Sell and Pay
summary: Create Sell and Pay transaction
description: >-
Creates a new Sell and Pay transaction for converting cryptocurrency to
fiat currency and paying a merchant via QR code. This endpoint
automatically cancels any existing Sell and Pay transactions for the
same customer. If all required fields are provided (customerId,
externalRef, qrCode, paymentCurrency, depositCurrency, depositNetwork,
and refundAddress), the transaction will be created with status PENDING.
If any required fields are missing, the transaction will be created with
status INCOMPLETE and must be completed using the update endpoint.
operationId: createSellAndPay
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SellAndPayRequest'
responses:
'201':
description: Sell and Pay transaction successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/SellAndPayResponse'
'400':
description: >-
Bad Request - e.g., invalid request data, validation error, or the
amount is outside the account's SELL limits.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
AmountBelowMinSellLimit:
summary: Amount below the minimum SELL limit
value:
code: 20052
type: SellAndPayAmountBelowMinSellLimitException
detail:
message: The amount is below the minimum SELL limit.
status: 400
AmountAboveMaxSellLimit:
summary: Amount above the maximum SELL limit
value:
code: 20053
type: SellAndPayAmountAboveMaxSellLimitException
detail:
message: The amount is above the maximum SELL limit.
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
'403':
description: >-
Forbidden - QR payments are not enabled for this account. Every Sell
and Pay endpoint requires QR payments to be enabled; contact Ripio
to enable it.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 40003
type: QrPaymentsNotEnabledException
detail:
message: QR payments are not enabled for this account.
status: 403
'404':
description: Not Found - e.g., Customer 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:
schemas:
SellAndPayRequest:
type: object
required:
- customerId
- externalRef
- qrCode
- paymentCurrency
properties:
customerId:
type: string
format: uuid
description: >-
Unique identifier of the customer initiating the Sell and Pay
transaction. Must be a valid customer registered in the system and
associated with the account.
example: b6cecc1f-c90d-424b-adaa-c82b780696c1
externalRef:
type: string
maxLength: 250
description: >-
External reference identifier for tracking purposes. This can be
used to correlate the transaction with external systems or partner
records.
example: sp-12345-2024
qrCode:
type: string
minLength: 1
description: >-
QR code data containing the payment information for the merchant.
This includes payment details such as recipient information and
amount to be paid in fiat currency.
example: >-
00020101021226360014BR.GOV.BCB.PIX0114+55119876543215204000053039865802BR5913Store
Name XYZ6009SAO PAULO62070503***6304ABCD
paymentCurrency:
type: string
enum:
- ARS
- COP
description: >-
Fiat currency in which the payment will be made to the merchant.
Must be one of the supported fiat currencies. Use `ARS` for
Argentina QR payments and `COP` for Colombia BREB-QR payments.
example: ARS
depositCurrency:
type: string
maxLength: 10
description: >-
Cryptocurrency that will be deposited by the customer (e.g., BTC,
ETH, USDC). If not specified, the system may use default settings or
require it during execution.
example: USDC
depositNetwork:
type: string
maxLength: 128
description: >-
Blockchain network for the cryptocurrency deposit (e.g., ETHEREUM,
POLYGON, BITCOIN). Required when depositCurrency is provided. Must
be a valid network supported for the specified deposit currency.
example: ETHEREUM
refundAddress:
type: string
maxLength: 255
description: >-
Cryptocurrency address to which funds should be refunded if the
transaction fails or is cancelled. Should be a valid address on the
deposit network.
example: '0x4e88BBeFF059BDDF5BF90ee0816E86eDf4214b32'
SellAndPayResponse:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the Sell and Pay transaction assigned by the
B2B Service
example: a3b2c1d0-1234-5678-90ab-cdef12345678
createdAt:
type: string
format: date-time
description: >-
Timestamp when the Sell and Pay transaction was created in ISO 8601
format
example: '2024-01-26T12:45:00.078230Z'
expiresAt:
type: string
format: date-time
description: >-
Timestamp when the transaction will expire if not completed in ISO
8601 format. After expiration, cryptocurrency deposits will not be
processed.
example: '2024-01-26T13:45:00.078230Z'
customerId:
type: string
format: uuid
description: Unique identifier of the customer who initiated the transaction
example: b6cecc1f-c90d-424b-adaa-c82b780696c1
trade:
anyOf:
- $ref: '#/components/schemas/SellAndPayTrade'
- type: 'null'
description: >-
Trade execution details. This will be null until the trade is
executed and contains information about the cryptocurrency-to-fiat
conversion.
paymentOrder:
anyOf:
- $ref: '#/components/schemas/SellAndPayPaymentOrder'
- type: 'null'
description: >-
Payment order details for the merchant payment. Contains information
about the QR code payment and merchant details.
amount:
type: string
description: Payment amount in fiat currency to be paid to the merchant
example: '10000.50'
cryptoAmount:
type: string
description: >-
Amount of cryptocurrency required to complete the payment,
calculated based on current exchange rates and fees
example: '10.25'
paymentCurrency:
type: string
description: Fiat currency code for the payment (e.g., ARS, MXN, USD)
example: ARS
depositCurrency:
type: string
description: Cryptocurrency code for the deposit (e.g., BTC, ETH, USDC)
example: USDC
depositNetwork:
type: string
description: >-
Blockchain network identifier for the cryptocurrency deposit (e.g.,
ETHEREUM, POLYGON, BITCOIN)
example: ETHEREUM
depositAddress:
type: string
description: >-
Cryptocurrency address where the customer should send the deposit.
This is a unique address generated for this transaction.
example: '0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D'
cryptoDeposit:
anyOf:
- $ref: '#/components/schemas/SellAndPayCryptoDeposit'
- type: 'null'
description: >-
Information about the cryptocurrency deposit made by the customer.
This will be null until a deposit is detected on the blockchain.
status:
type: string
enum:
- INCOMPLETE
- PENDING
- WAITING_DEPOSIT
- RECEIVED_DEPOSIT
- CONFIRMED_DEPOSIT
- TRADE_COMPLETED
- QR_EXECUTION_PENDING
- COMPLETED
- CANCELED
- REFUND_PENDING
- REFUNDED
description: >-
Current status of the Sell and Pay transaction. INCOMPLETE: missing
required fields. PENDING: ready to execute. WAITING_DEPOSIT:
executed and ready to receive crypto deposit. RECEIVED_DEPOSIT:
crypto deposit detected on blockchain. CONFIRMED_DEPOSIT: crypto
deposit confirmed. TRADE_COMPLETED: cryptocurrency successfully
converted to fiat. QR_EXECUTION_PENDING: preparing payment to
merchant. COMPLETED: payment successfully made to merchant.
CANCELED: transaction cancelled. REFUND_PENDING: refund being
processed. REFUNDED: funds refunded to customer.
example: PENDING
refundAddress:
type:
- string
- 'null'
description: >-
Cryptocurrency address for refunds in case of transaction failure or
cancellation
refundTxnHash:
type:
- string
- 'null'
description: >-
Transaction hash for the refund transaction on the blockchain.
Present when a refund has been processed.
example: 0xdef789abc456...
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
SellAndPayTrade:
type: object
description: Details of the cryptocurrency-to-fiat trade execution
properties:
id:
type: string
description: Unique identifier for the trade
createdAt:
type: string
format: date-time
description: Timestamp when the trade was executed
externalRef:
type: string
description: External reference from the original transaction request
customerId:
type: string
description: Customer identifier (end user) for the trade
quoteId:
type: string
description: Identifier of the quote used for this trade
txnId:
type: string
description: Transaction identifier from the B2B Service
baseAsset:
type: string
description: Base asset in the trade pair (cryptocurrency)
quoteAsset:
type: string
description: Quote asset in the trade pair (fiat currency)
baseAmount:
type: string
description: Amount of base asset (cryptocurrency) used in the trade
quoteAmount:
type: string
description: Amount of quote asset (fiat currency) received from the trade
rate:
type: string
description: Exchange rate applied to the trade including all fees and spreads
marketRate:
type: string
description: Market exchange rate at the time of trade execution
chargedFee:
type: string
description: Total fee charged for the trade in fiat currency
cryptoChargedFee:
type: string
description: Fee charged in cryptocurrency
deferredChargedFee:
type: string
description: Deferred fee amount that may be charged later
feeChargedInFiat:
type: string
description: Total fee amount charged in fiat currency
SellAndPayPaymentOrder:
type: object
description: Details of the payment order to the merchant
properties:
id:
type: string
description: Unique identifier for the payment order
customerId:
type: string
description: Customer identifier (end user) making the payment
createdAt:
type: string
format: date-time
description: Timestamp when the payment order was created
merchant:
type: string
description: Merchant identifier or name receiving the payment
qrCode:
type: string
description: Original QR code data containing payment information
amount:
type: string
description: Payment amount in fiat currency
currency:
type: string
description: Fiat currency code for the payment
providerTxnId:
type:
- string
- 'null'
description: >-
Transaction identifier from the payment provider. Will be null until
the payment is processed.
SellAndPayCryptoDeposit:
type: object
description: Information about the cryptocurrency deposit received from the customer
properties:
id:
type: string
description: Unique identifier for the crypto deposit record
txnId:
type: string
description: Transaction identifier in the B2B Service
hash:
type: string
description: Blockchain transaction hash for the deposit
currencyCode:
type: string
description: Cryptocurrency code of the deposited asset (e.g., BTC, ETH)
addressDestination:
type: string
description: Destination address that received the cryptocurrency deposit
confirmationDate:
type: string
format: date-time
description: Timestamp when the deposit was confirmed on the blockchain
amount:
type: string
description: Amount of cryptocurrency deposited
createdAt:
type: string
format: date-time
description: Timestamp when the deposit record was created
customerId:
type: string
description: Customer identifier (end user) who made the deposit
status:
type: string
description: Status of the crypto deposit (e.g., PENDING, CONFIRMED, PROCESSING)
network:
type: string
description: >-
Blockchain network where the deposit was made (e.g., ETHEREUM,
POLYGON)
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 `.
````