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

# QR payments integration

> Step-by-step walkthrough to let your users pay a merchant's QR code with crypto using Sell and Pay, in Argentina and Colombia.

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

> [!NOTE]
>
> QR payments are available **through the API only** — the [Widget](https://docs.ripio.com/ramps-api/widget/overview.md) 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

| Country | `paymentCurrency` | QR standard | Sell and Pay fiat account |
| - | - | - | - |
| [Argentina](https://docs.ripio.com/ramps-api/overview/countries/argentina.md) | `ARS` | QR | **Required** — one per customer, created with [Create Fiat Account for Sell and Pay](https://docs.ripio.com/ramps-api/sell-and-pay/create-fiat-account.md) |
| [Colombia](https://docs.ripio.com/ramps-api/overview/countries/colombia.md) | `COP` | BRE-B QR | **Not used** — calling the endpoint returns `400 SellAndPayFiatAccountNotRequiredException` |

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.

> [!NOTE]
>
> The **Sell and Pay fiat account** is not the same as the [external fiat account](https://docs.ripio.com/ramps-api/fiat-accounts/create-fiat-account.md) 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](https://docs.ripio.com/ramps-api/authentication/acquire-access-token.md)

**2. Create the customer**

Register the end user and keep the returned `customerId`.

→ [Create Customer](https://docs.ripio.com/ramps-api/customers/create-customer.md)

**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](https://docs.ripio.com/ramps-api/terms-and-conditions/introduction.md) · [Accept Terms](https://docs.ripio.com/ramps-api/customers/accept-terms.md)

**4. Verify identity (KYC)**

The customer must be active and reach KYC status `COMPLETED` before creating a Sell and Pay transaction.

→ [Identity verification (KYC)](https://docs.ripio.com/ramps-api/kyc/overview.md)

**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](https://docs.ripio.com/ramps-api/sell-and-pay/create-fiat-account.md)

## 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](https://docs.ripio.com/ramps-api/sell-and-pay/validate-qr-code.md)

**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](https://docs.ripio.com/ramps-api/sell-and-pay/create-sell-and-pay.md)

**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](https://docs.ripio.com/ramps-api/sell-and-pay/update-sell-and-pay.md)

**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](https://docs.ripio.com/ramps-api/sell-and-pay/execute-sell-and-pay.md)

**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](https://docs.ripio.com/ramps-api/webhooks/sell-and-pay-events.md) — `SELL_AND_PAY.PAYMENT_ORDER.COMPLETED` means the merchant was paid — or poll [Retrieve Sell and Pay](https://docs.ripio.com/ramps-api/sell-and-pay/retrieve-sell-and-pay.md).

To cancel a payment the user abandons, delete it while it is still `INCOMPLETE`, `PENDING` or `WAITING_DEPOSIT` with [Delete Sell and Pay](https://docs.ripio.com/ramps-api/sell-and-pay/delete-sell-and-pay.md).

## Transaction lifecycle

| Status | Meaning |
| - | - |
| `INCOMPLETE` | Created with required fields missing. Complete it with the update endpoint. |
| `PENDING` | All fields present, ready to execute. |
| `WAITING_DEPOSIT` | Executed; waiting for the user's crypto at `depositAddress`. |
| `RECEIVED_DEPOSIT` | Deposit detected on-chain. |
| `CONFIRMED_DEPOSIT` | Deposit confirmed. |
| `TRADE_COMPLETED` | Crypto sold for fiat. |
| `QR_EXECUTION_PENDING` | Payment to the merchant in progress. |
| `COMPLETED` | The merchant was paid. |
| `CANCELED` | The transaction was cancelled. |
| `REFUND_PENDING` | The deposit is being returned to `refundAddress`. |
| `REFUNDED` | The deposit was returned to `refundAddress`. |

`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](https://docs.ripio.com/ramps-api/sell-and-pay/create-sell-and-pay.md).


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