Skip to main content
Currency: BRL · On-Ramp: ✅ · Off-Ramp: ✅

​
Payment methods

​
On-Ramp (fiat → crypto)

​
Off-Ramp (crypto → fiat)

Brazil has no reusable deposit account. Each on-ramp order returns its own payment instructions synchronously in fiatPaymentInstructions, so there is nothing to create beforehand and nothing to wait for.

​
On-Ramp payment instructions

Create On-Ramp Order returns the PIX payment instructions in fiatPaymentInstructions:
The payment instructions are bound to the customer’s own verified identity: only the CPF/CNPJ from their approved KYC is allowed to pay them. A transfer attempted by anyone else will not go through, so never reuse one customer’s BR Code for another.
Because the payable object belongs to a single order, pix is not available through an On-Ramp Session — use Create On-Ramp Order.

​
Requirements

  • Customer & KYC: the customer must complete identity verification (COMPLETED) before operating. Brazil KYC requires first_name, last_name, id_number, id_number_type and net_income in addition to location and contact fields — see the fields Brazil requires. The approved CPF/CNPJ and customer name bind on-ramp payment instructions to the verified customer, and the document is also used to verify ownership of PIX destination accounts.
  • Deposit account (On-Ramp): not required. Create Deposit Account is a no-op for pix and returns 200 OK; you can skip it entirely.
  • Off-Ramp destination account: register the user’s destination PIX key as an external fiat account — a single pix_key field, which may be a CPF, CNPJ, email, phone or EVP (random) key (see PIX key formats below). 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. On a match the account is created as unconfirmed and must be confirmed before it can receive a payout — see What the key resolves to for the other endings. Use Retrieve Fiat Account Requirements to get the exact fields.
  • Terms & Conditions: accept the applicable T&C right after creating the customer — a required step before operating.

​
PIX key formats

pix_key is a single free-text field with no type selector: the type is inferred from the value and the account holder is resolved from the key itself. So the key has to arrive in the same canonical format BACEN registered it in — a key that is merely recognisable to a human is not resolvable. Maximum length is 77 characters (the EMV/BACEN limit).
A phone key must carry the + and the country code. Without it the key is not the one registered at BACEN, so sending 5511987654321 or 11987654321 is rejected with a 400 naming the expected format. Send +5511987654321.This is also why the other types must be sent bare: an 11-digit key with no + is read as a CPF, which is exactly what a Brazilian mobile number looks like when the prefix is dropped.The rejection is a plain validation error, raised before the key is looked up:

​
What the key resolves to

There is nothing to poll: the key is looked up while Create Fiat Account is being served, so the answer is in that response. It has four endings, and they are not interchangeable — three of them are the customer’s to fix, and each one needs different words. A malformed value never reaches the lookup: it is a 400 with code 20000, like the phone-prefix case above.
The resolved holder comes back in metadata, in both 201 endings — name, the masked tax_id and bank_name. That is what lets you show the customer whose account they are about to be paid into before confirming, and, when the account comes back disabled, explain why instead of showing a generic failure.
BACEN masks the document, so you get enough for the customer to recognise the holder and not enough to identify a stranger.

​
Refunds

On-ramp deposits in Brazil are refunded by reversing the customer’s own PIX transfer, so the money goes back to the account it came from and you never name a destination: refundDestinationRequired is false. See Refunds.

​
Next steps