BrazilianHubBrazilianHubdocs

Documentação

Métodos de pagamento por moeda

Cada moeda tem os seus meios de pagamento. É sempre o mesmo endpoint — POST /transactions/v2/purchase — mudando currency e, quando a moeda tem mais de um trilho, paymentMethod.

MoedaMétodopaymentMethodInstruçãoCampo na resposta
🇧🇷 BRLPIX"PIX" (obrigatório)na respostapixCode
🇧🇷 BRLCartão"CREDIT_CARD"——
🇧🇷 BRLBoleto"BOLETO"na resposta (após registro)boletoDigitableLine + boletoBarcode
🇧🇷 BRLPix ou Boleto"PIX_BOLETO"na resposta (após registro)pixCode + boletoDigitableLine
🇲🇽 MXNSPEI"SPEI" (padrão)na respostaclabe
🇲🇽 MXNOXXO"OXXO"na respostareference + barcode
🇦🇷 ARSTransferência"BANK_TRANSFER" (padrão)por webhookcvu
🇨🇴 COPTransferência"BANK_TRANSFER" (padrão)por webhookredirectUrl
🇨🇴 COPPSE"PSE"por webhookredirectUrl
🇨🇴 COPNequi (push)"NEQUI"— (aprova no app)—
🇨🇴 COPNequi QR"NEQUI_QR"na respostaqr
🇨🇴 COPBre-B QR"BREB"na respostaqr
🇨🇴 COPBre-B chave"BREB_KEY"na respostareference
🇧🇴 BOBQR"QR" (padrão)por webhookqr
🇨🇱 CLPTransferência"BANK_TRANSFER" (padrão)na respostaredirectUrl
🇨🇱 CLPCartão"CARD"na respostaredirectUrl
🇨🇱 CLPCarteira digital"WALLET"na respostaredirectUrl

Omitir paymentMethod usa o padrão da moeda. Só o BRL exige o campo, por compatibilidade com a integração antiga.

A moeda é fixa por conta e trava na primeira venda. Para operar em outro país, crie uma empresa nova pelo painel.

Saque é sempre em BRL. Não existe cash-out em peso ou boliviano: o saldo que entra em MXN, ARS, COP, BOB ou CLP é liquidado para real pela BrazilianHub e sacado pelo fluxo normal — POST /withdraws/cash-out, o mesmo de uma conta brasileira. Você não pede a conversão nem aprova cotação; ela é operada por nós e o saldo em BRL aparece sozinho. Enquanto não liquidado, o saldo na moeda local ainda não é sacável — GET /accounts/balances mostra as duas linhas.

A diferença que mais quebra integração

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) e CLP (Chile). Você cria a cobrança e já mostra o código (ou o redirectUrl do Chile) 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.

Dados do pagador exigidos

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

MoedanameemailphoneDocumento
BRL (PIX/Cartão)simopcionalsimCPF/CNPJ em cpf
BRL (Boleto / Pix ou Boleto)simopcionalsimCPF/CNPJ em cpf + endereço
MXN (SPEI)simopcionalnãonão
MXN (OXXO)simsimnãonão
ARSsimsimopcionalnão
COP (Transfer/PSE)simsimsimCC, NIT, CE ou TI
COP (Nequi)opcionalopcionalsim — 10 díg, sem +57opcional
COP (Nequi QR / Bre-B / chave)nãonãonãonão
BOBsimsimsimCI, NIT ou PAS
CLP (Transfer/Cartão/Carteira)simsimrecomendadoRUT (validado — ver abaixo)

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

No PSE e na transferência a Colômbia é a mais exigente (os quatro dados, senão a rede recusa). O Nequi exige só o telefone (10 dígitos, sem +57). Os QR/chave (Nequi QR, Bre-B, Bre-B chave) não pedem dado do pagador — só o valor.

O Chile exige name, email e o RUT (documento tributário chileno) em responsibleDocument — nos três métodos. O RUT é validado pelo dígito verificador: um RUT inválido é recusado com 400 antes de criar a cobrança. Aceita com ou sem pontos, com hífen antes do dígito (12.345.678-5, 12345678-5 ou 123456785); o dígito verificador pode ser K. O phone é recomendado, não obrigatório.

Valores e limites

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

MoedaMínimoMáximoamount do mínimo
MXN—por conta1000 = MX$ 10,00
ARSAR$ 2.000AR$ 1.000.000200000
COPCOP 10.000COP 10.000.0001000000
BOBBs 10Bs 10.0001000
CLPCLP$ 1.000CLP$ 5.000.000100000

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.

Peso chileno (CLP) não tem centavos — mas amount continua em centavos, como nas outras moedas. CLP$ 1.000 é 100000, não 1000. Mande sempre múltiplos de 100 (um valor com fração de peso é arredondado para o peso inteiro antes de ir à rede). Os limites de CLP são estimados e podem ser ajustados conforme a rede chilena confirmar.

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.

Taxa por método

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.

Boleto (BRL)

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.

JSON
{
  "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.