Skip to main content
Sell and Pay lets your users pay any merchant QR code with crypto. The user scans the merchant’s QR, sends crypto to a deposit address, and Ripio sells it for fiat and pays the merchant in local currency. The merchant receives a regular local payment; it never touches crypto. For request and response details, follow the endpoint link in each step.
QR payments are available through the API only — the Widget does not support them. They are also not enabled by default: every Sell and Pay endpoint returns 403 QrPaymentsNotEnabledException until Ripio enables QR payments on your account. Contact your Ripio representative to turn them on.

​
Country support

Both fixed-amount QR codes (the amount is encoded in the QR) and open-amount QR codes (the amount is entered at payment time) are supported in both countries.
The Sell and Pay fiat account is not the same as the external fiat account used for Off-Ramp payouts. Ripio sets it up on the customer’s behalf to pay merchants, so it only takes a customerId. You don’t need to register or confirm any bank account for QR payments.

​
Common setup

1

Authenticate

Get an access token with the OAuth2 Client Credentials flow and send it as a Bearer token on every call.→ Acquire Access Token
2

Create the customer

Register the end user and keep the returned customerId.→ Create Customer
3

Accept Terms & Conditions

Right after creating the customer, register their acceptance of the active Terms & Conditions. A new version for the country blocks the customer again until they accept it.→ Terms & Conditions · Accept Terms
4

Verify identity (KYC)

The customer must be active and reach KYC status COMPLETED before creating a Sell and Pay transaction.→ Identity verification (KYC)
5

Argentina only: create the Sell and Pay fiat account

Once KYC is completed, create the customer’s Sell and Pay fiat account. Do it once per customer, ahead of their first payment: if you skip it, the account is created during the first Sell and Pay instead, and that payment takes noticeably longer.Skip this step in Colombia — BRE-B QR payments don’t use a customer fiat account, and the call fails with 400 SellAndPayFiatAccountNotRequiredException.→ Create Fiat Account for Sell and Pay

​
Pay a QR code

1

Validate the scanned QR (optional)

When the user scans a QR in your app, send its raw content to validate it and get the merchant name. Use it to show the user who they are about to pay before committing to anything. An invalid or unsupported QR returns 400 InvalidQRCodeException.→ Validate QR Code
2

Create the Sell and Pay

Create the transaction with the customerId, your externalRef, the raw qrCode content and the paymentCurrency of the country (ARS or COP). Add the crypto the user will pay with — depositCurrency and depositNetwork — and a refundAddress on that network.
  • With all of them present, the transaction is created as PENDING.
  • If any is missing, it is created as INCOMPLETE and you complete it in the next step.
A customer can have only one Sell and Pay in progress: creating a new one cancels any open Sell and Pay of the same customer. The response includes cryptoAmount (how much crypto covers the payment) and an expiresAt.→ Create Sell and Pay
3

Complete the details, or set the amount for an open-amount QR

Use the update endpoint to fill in whatever was missing — depositCurrency, depositNetwork, refundAddress — or, for an open-amount QR, the amount in fiat that the user wants to pay. Once every required field is present, the status moves from INCOMPLETE to PENDING.The amount must fall within your account’s sell limits; otherwise the request fails with an amount-below-minimum or above-maximum error.→ Update Sell and Pay
4

Execute it and show the deposit address

Once the user confirms the amount, execute the transaction. It moves to WAITING_DEPOSIT and returns the depositAddress. Show the user the address, the exact cryptoAmount and the network, and ask them to send the crypto before expiresAt — after expiration, deposits are no longer processed.→ Execute Sell and Pay
5

User sends crypto — Ripio sells it and pays the merchant

When the deposit is confirmed on-chain, Ripio sells the crypto for fiat and pays the merchant through the QR. Follow the progress with Sell and Pay webhook events — SELL_AND_PAY.PAYMENT_ORDER.COMPLETED means the merchant was paid — or poll Retrieve Sell and Pay.
To cancel a payment the user abandons, delete it while it is still INCOMPLETE, PENDING or WAITING_DEPOSIT with Delete Sell and Pay.

​
Transaction lifecycle

INCOMPLETE, PENDING and WAITING_DEPOSIT can still be cancelled; from RECEIVED_DEPOSIT on, the transaction can only finish as COMPLETED or be refunded.

​
Refunds

If the payment can’t go through — the deposit is blocked, or the transaction fails or is cancelled after the crypto arrived — Ripio returns the crypto to the refundAddress automatically and sends SELL_AND_PAY.DEPOSIT.REFUND_PROCESSING. Crypto sent to a Sell and Pay address with no transaction behind it is also returned, with SELL_AND_PAY.DEPOSIT_WITHOUT_SELL_AND_PAY.REFUND_PROCESSING. Unlike Off-Ramp, there is no refund request for you to make.

​
Testing in sandbox

The sandbox accepts a set of test QR codes that simulate a successful payment with and without an amount, an invalid QR, a blocked deposit and slippage in Argentina, plus fixed- and open-amount BRE-B QR codes for Colombia. You’ll find them under Create Sell and Pay.