Métodos de pagamento por moeda

Nem toda moeda entrega a instrução de pagamento na mesma hora, e isso muda o seu código.

Instrução na resposta — BRL, MXN (SPEI e OXXO). Você cria a cobrança e já mostra o código na tela. Fluxo de uma chamada.

Instrução por webhook — ARS, COP, BOB. A criação volta com status: "PENDING" e o campo da instrução vazio. Isso é o comportamento normal, não é erro: o identificador é negociado com a rede local e fica pronto em alguns segundos. Faça polling em GET /transactions/:id até o campo vir preenchido.

Boleto (BRL) fica no meio: a boletoDigitableLine e o boletoBarcode só existem após o registro na Núclea — podem vir já na criação ou alguns instantes depois. Trate como o caso assíncrono: se vierem vazios, 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 (até o vencimento). O valor cai no mesmo saldo do PIX (BRL).

Se a sua tela assume que o código sempre vem na criação, ela quebra no primeiro país assíncrono.

Cada rede pede um conjunto diferente. Faltando qualquer um dos obrigatórios, a cobrança é recusada antes de ser criada.

O cpf é documento brasileiro e só se aplica ao BRL. Nos demais países o documento do pagador vai em responsibleDocument.

A Colômbia é a mais exigente das cinco: sem os quatro dados a rede recusa direto.

amount é sempre em centavos, em todas as moedas — inclusive naquelas em que ninguém usa centavos no dia a dia.

Atenção ao peso colombiano. COP 10.000 é 1000000 em centavos, não 10000. Mandar 10000 pede COP 100 e leva erro de valor fora da faixa.

Além do limite da rede, a sua conta tem limites próprios por método, configuráveis no painel. Uma cobrança fora deles é recusada mesmo estando dentro do que a rede aceita.

Métodos da mesma moeda podem ter preços diferentes — e costumam ter. No México, o SPEI cobra uma taxa fixa por transferência enquanto o OXXO cobra percentual, porque a loja fica com uma parte.

Cada método tem a sua taxa configurada na sua conta. O costFee que volta na criação já reflete a do método usado naquela cobrança.

Antes de ofertar um método novo aos seus compradores, confira o preço dele no painel — ofertar OXXO achando que custa o mesmo que SPEI é a forma mais rápida de vender no prejuízo.

O boleto registrado é um método de BRL que liquida no mesmo saldo do PIX — mas o pagador paga depois (banco/app até o vencimento) e a baixa chega pelo webhook cashin.paid.

É o mesmo endpoint — POST /transactions/v2/purchase — com paymentMethod: "BOLETO". Como o boleto registrado exige o endereço do pagador, mande o objeto boletoAddress. O vencimento é opcional (dueDate, YYYY-MM-DD); sem ele, usamos hoje + 3 dias.

{
  "amount": 5000,
  "paymentMethod": "BOLETO",
  "name": "Maria Souza",
  "email": "maria@exemplo.com",
  "cpf": "12345678901",
  "phone": "11999998888",
  "dueDate": "2026-10-20",
  "boletoAddress": {
    "address": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "district": "Centro",
    "city": "São Paulo",
    "zipCode": "01001000",
    "uf": "SP"
  }
}

Campos obrigatórios do boletoAddress: address, district, city, zipCode (8 dígitos) e uf (2 letras). number e complement são opcionais.

A resposta volta com boletoDigitableLine (linha digitável) e boletoBarcode (código de barras) — que podem chegar logo após o registro na Núclea (faça polling em GET /transactions/:id se vierem vazios). A confirmação do pagamento é assíncrona: o webhook cashin.paid dispara quando o boleto é pago.