Documentação
Brasil (BRL)
No Brasil, as contas operam em BRL (reais) sobre o PIX — a rede de pagamentos instantâneos do Banco Central. É o comportamento padrão da API: se você não enviar currency, tudo roda em BRL/PIX. O cash-in acontece pelo mesmo endpoint de sempre — POST /transactions/v2/purchase — com paymentMethod: "PIX".
A resposta traz um BR Code copia-e-cola (pixCode): é o código que você mostra pro cliente (como texto pra copiar ou renderizado em QR Code) e que ele paga por qualquer app de banco. Quando o PIX cai, disparamos o webhook cashin.paid.
O BRL tem quatro meios de pagamento, todos no mesmo endpoint — muda só o paymentMethod: PIX ("PIX", padrão/instantâneo), Cartão de crédito ("CREDIT_CARD"), Boleto ("BOLETO", registrado) e Pix ou Boleto ("PIX_BOLETO", híbrido — o pagador escolhe). Veja as seções de Boleto e Pix ou Boleto abaixo e Métodos de pagamento por moeda.
amounté sempre em centavos:1000= R$ 10,00. Ocpf(CPF ou CNPJ do pagador) é obrigatório no BRL.
Os meios de pagamento no BRL
paymentMethod | O que é | Instrução na resposta | Confirmação |
|---|---|---|---|
"PIX" (padrão) | pagamento instantâneo | pixCode (BR Code copia-e-cola) | segundos (webhook cashin.paid) |
"CREDIT_CARD" | cartão de crédito (tokenizado) | — (síncrono) | na hora |
"BOLETO" | boleto registrado | boletoDigitableLine + boletoBarcode | até o vencimento (webhook cashin.paid) |
"PIX_BOLETO" | híbrido: uma cobrança paga por PIX ou boleto | pixCode e boletoDigitableLine | PIX em segundos ou boleto até o vencimento (webhook cashin.paid) |
Boleto e Pix ou Boleto exigem o endereço do pagador (objeto
boletoAddress) e liquidam no mesmo saldo do PIX. Detalhes nas seções abaixo.
Como funciona o cash-in em PIX
| Item | BRL (PIX) |
|---|---|
currency | "BRL" (padrão — pode omitir) |
paymentMethod | "PIX" |
amount | em centavos (1000 = R$ 10,00) |
cpf / phone | obrigatórios |
| Resposta | pixCode (BR Code copia-e-cola) + method: "PIX" |
| Confirmação | webhook cashin.paid |
Veja Métodos de pagamento por moeda para a lista completa de trilhos, dados exigidos e limites de cada país.
A moeda é fixa por conta: uma conta BRL opera sempre em reais — saldo, taxas, faturas e transações todos em BRL — e não pode ser trocada depois da primeira transação. Para receber em pesos mexicanos via SPEI, veja México (MXN) e Criar transação (MXN / SPEI). Para pesos argentinos, Argentina (ARS) e Criar transação (ARS). Para pesos colombianos, Colômbia (COP) e Criar transação (COP). Para bolivianos, Bolívia (BOB) e Criar transação (BOB).
Boleto
O boleto registrado é um meio de pagamento do BRL: o pagador paga em qualquer banco/app até o vencimento e o valor cai no mesmo saldo do PIX — sem mudar o seu fluxo de saque. É o mesmo endpoint com paymentMethod: "BOLETO" — payload completo, parâmetros e exemplos em Criar transação (Boleto).
Como o boleto é emitido na rede bancária (Núclea), ele exige o endereço do pagador (boletoAddress):
| Campo | Obrigatório | Observação |
|---|---|---|
paymentMethod | sim | "BOLETO" |
boletoAddress | sim | address, district, city, zipCode (8 díg.), uf (2 letras); number/complement opcionais |
dueDate | não | YYYY-MM-DD; sem ele, hoje + 3 dias |
A resposta volta com status: "PENDING" e, após o registro, com boletoDigitableLine (linha digitável) e boletoBarcode. Se vierem vazios na criação, faça polling em GET /transactions/:id. Diferente do PIX, o boleto não é instantâneo: a baixa chega pelo webhook cashin.paid quando o pagador paga.
Está disponível no checkout de ofertas, links de pagamento, faturas (marque BOLETO em paymentMethods — veja Criar fatura) e na API. Habilitar numa conta exige uma lista de contingência do tipo BOLETO (configuração no painel administrativo).
Pix ou Boleto (híbrido)
Pix ou Boleto é o método híbrido do BRL: uma única cobrança que o pagador quita por PIX (na hora) ou por boleto (até o vencimento). Ele escolhe; você não emite duas cobranças. É o mesmo endpoint com paymentMethod: "PIX_BOLETO" — payload completo, parâmetros e exemplos em Criar transação (Pix ou Boleto).
O payload é idêntico ao do boleto (exige boletoAddress); muda só o paymentMethod. A resposta traz as duas instruções ao mesmo tempo:
| Campo da resposta | O que é |
|---|---|
pixCode | BR Code copia-e-cola do PIX (instantâneo) |
boletoDigitableLine + boletoBarcode | boleto (até o vencimento) |
dueDate | vencimento do boleto |
Vale pagar só um dos dois — quando qualquer trilho é pago, a cobrança é baixada e o outro deixa de valer. Se os campos vierem vazios na criação, faça polling em GET /transactions/:id. A confirmação chega pelo webhook cashin.paid e liquida no mesmo saldo do PIX.
Está disponível no checkout de ofertas e links de pagamento (o comprador recebe o QR do PIX com o boleto como alternativa) e na API. Usa a mesma lista de contingência do tipo BOLETO.