Available payout methods depend on the country. See Countries & payment methods first. In Colombia, Request-to-Pay (R2P) is On-Ramp only and cannot be used for payouts.
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 Token2
Create the customer
Register the end user and keep the returned
customerId.→ Create Customer3
Accept Terms & Conditions
Right after creating the customer, register their acceptance of the active Terms & Conditions. This is a required step before the customer can operate.It is also a recurring one: acceptance covers the version that was shown, so a new version for the country blocks the customer again until they accept it. Re-check before operating instead of storing the result.→ Terms & Conditions · Accept Terms
4
Verify identity (KYC)
The customer must reach KYC status
COMPLETED before operating.→ Identity verification (KYC)5
Brazilian accounts: collect the investor profile
If your account is in Brazil, your customers must answer a short suitability questionnaire after KYC and before their first order or session, and again every year. Check the status, show the questionnaire when it is
REQUIRED or EXPIRED, and submit the answers; without it, creating an order, a session or a destination account fails with 20100. Accounts in other countries skip this step, whatever the customer’s nationality.→ Investor Profile (Brazil)6
Register and confirm the payout account
Register the user’s destination bank account (their external fiat account) — for example a CBU/CVU/alias in Argentina, a CLABE in Mexico, a PSE/BRE-B account in Colombia, or a PIX key in Brazil. First fetch the required fields, then create the account and confirm it.Validation may be synchronous (usable right away) or asynchronous (it starts in → Retrieve Fiat Account Requirements · Create Fiat Account · Confirm Fiat Account · Create Deposit Account
processing and becomes usable once validation returns). It must be enabled before it can receive a payout. Keep its fiatAccountId — the session needs it.In Brazil (PIX) the account is a single
pix_key field and there is no deposit-account prerequisite. The key is resolved to its account holder while the request is served, and the holder’s document must match the customer’s own CPF/CNPJ — a key belonging to someone else comes back disabled. There is no type selector, so each key type must arrive in its canonical format; in particular a phone key needs the + and the country code (+5511987654321). See PIX key formats.Set up the off-ramp session
1
Create the off-ramp session
Create a session with the destination
fiatAccountId. The response includes the crypto deposit addresses (one per supported network). The session is reusable and does not expire.→ Create Off-Ramp Session2
User sends crypto — orders are created automatically
Each time the customer sends crypto to a session deposit address, an off-ramp order is created automatically, a fresh quote is applied, the trade executes and the fiat is paid out. No per-deposit API call is needed.Track each order with Off-Ramp Events or by inspecting the session’s transactions via Retrieve an Off-Ramp Session.
Order lifecycle
Resolving a cancelled order
refundable on the order tells you which way out it has, and failureReason tells you what went wrong:
The two paths are mutually exclusive: an order is refundable or reprocessable, never both. If neither resolves it, contact Ripio support.
Payout account states
|
revalidation_required | The account must be re-validated before it can be used again. |
Only one account can be active per payment method at a time. See Fiat account lifecycle for the full state model and how to reactivate a suspended account.