BrazilianHubBrazilianHubdocs

Documentação

Colômbia (COP)

A Colômbia tem quatro meios de pagamento — transferência bancária, PSE, Nequi e Bre-B — na moeda COP (pesos colombianos). Escolha pelo campo paymentMethod; sem ele, o padrão é transferência bancária. Mesmo endpoint de sempre — POST /transactions/v2/purchase — mudando currency para "COP".

Diferente do PIX e do SPEI, aqui o pagador não copia um código: ele é enviado para a página do banco dele, onde autoriza a transferência. O que você recebe é um redirectUrl — redirecione o comprador para lá.

A instrução não vem na resposta da criação. Igual à Argentina, o redirectUrl é negociado com a rede local e fica pronto alguns segundos depois. A resposta volta com status: "PENDING" e o campo vazio — é o comportamento normal, não é erro. Faça polling em GET /transactions/:id até vir preenchido.

Quando a transferência cai, disparamos o webhook cashin.paid — igual ao PIX.

Só habilite COP se a sua conta estiver habilitada para COP. A moeda da transação precisa casar com a moeda da conta.

Os quatro meios de pagamento

A Colômbia aceita seis trilhos de entrada, todos no mesmo endpoint — muda só o paymentMethod, e a instrução chega de um jeito diferente por método:

paymentMethodO que éComo chega a instrução
"BANK_TRANSFER"transferência bancária (padrão)redirectUrl por webhook
"PSE"débito online pelo banco do comprador (o meio dominante)redirectUrl por webhook
"NEQUI"carteira digital — aprova no próprio app Nequi (push)nenhuma — o pagador aprova no app
"NEQUI_QR"o comprador escaneia um QR NequiQR inline na resposta (qr)
"BREB"instantâneo do banco central — QR Bre-BQR inline na resposta (qr)
"BREB_KEY"transferência para uma chave Bre-Bchave inline na resposta (reference)

Omitir paymentMethod usa BANK_TRANSFER. NEQUI_QR e BREB_KEY são habilitados por conta — se a sua não tiver, a criação volta 400.

Dados do pagador por método:

  • BANK_TRANSFER / PSE: exigem name, phone, email e responsibleDocument (CC/NIT/CE/TI).
  • NEQUI: exige só o phone do comprador — 10 dígitos, sem +57 (ex.: 3001234567; com +57/espaços/traços a rede recusa com 400). name/email/responsibleDocument são recomendados.
  • NEQUI_QR / BREB / BREB_KEY: só o valor — não precisam de dados do pagador.

Faixa da rede: COP 10.000 a COP 10.000.000 por transação. Os QR/chave (NEQUI_QR, BREB, BREB_KEY) expiram em ~15–45 min; se expirar, crie uma nova cobrança.

Exemplos — um por método

PSE / Transferência — o comprador autoriza na página do banco. Exigem name, email, phone e responsibleDocument:

JSON
{
  "name": "Carlos Gómez",
  "email": "carlos@ejemplo.com",
  "phone": "+573001234567",
  "amount": 5000000,
  "currency": "COP",
  "paymentMethod": "PSE",
  "description": "Suscripción Pro",
  "responsibleDocument": "11987654321",
  "responsibleExternalId": "user-1234"
}

A resposta volta status: "PENDING" e o redirectUrl chega por webhook — mande o comprador para essa URL.


Nequi (push) — o comprador aprova no próprio app Nequi. Exige só o phone — 10 dígitos, sem +57 (3001234567); name/email/responsibleDocument são recomendados:

JSON
{
  "phone": "3001234567",
  "amount": 5000000,
  "currency": "COP",
  "paymentMethod": "NEQUI",
  "description": "Suscripción Pro"
}

Não há QR nem link. A resposta não traz instrução — diga ao comprador para abrir o Nequi e aprovar a notificação. A confirmação chega por webhook quando ele aprova.


Nequi QR / Bre-B — o comprador escaneia um QR. Precisa só do valor; o qr vem na própria resposta:

JSON
{
  "amount": 5000000,
  "currency": "COP",
  "paymentMethod": "BREB"
}

Resposta (resumida):

JSON
{
  "status": "PENDING",
  "method": "BREB",
  "payeeData": { "transferType": "QR", "qr": "00020101...6304ABCD" },
  "checkoutUrl": "https://checkout.example.com/9f2c1e40"
}

Renderize o qr como QR Code e um link clicável embaixo (checkoutUrl) — quem paga pelo celular não escaneia um QR exibido na própria tela. O QR expira em ~15 min (Bre-B) / ~45 min (Nequi QR); se expirar, crie outra cobrança.


Bre-B chave (BREB_KEY) — o comprador transfere para uma chave Bre-B. Precisa só do valor; a chave vem na resposta em reference:

JSON
{
  "amount": 5000000,
  "currency": "COP",
  "paymentMethod": "BREB_KEY"
}

Resposta (resumida):

JSON
{
  "status": "PENDING",
  "method": "BREB_KEY",
  "payeeData": { "transferType": "REFERENCE", "reference": "@Hq4tZ8mWv2LpR6nB" },
  "checkoutUrl": "https://checkout.example.com/9f2c1e40"
}

Mostre a chave e o valor exato (o comprador digita os dois no app do banco), ou mande para o checkoutUrl.

NEQUI_QR e BREB_KEY são habilitados por conta — se a sua não tiver, a criação volta 400. A taxa pode variar por método; confira o preço de cada um no painel antes de ofertar.

O que muda em relação ao BRL

CampoBRL (PIX)COP (Transferência)
currency"BRL" (padrão)"COP" (obrigatório)
paymentMethodobrigatório ("PIX")opcional — default BANK_TRANSFER
nameobrigatórioobrigatório
emailopcionalobrigatório
phoneobrigatórioobrigatório
responsibleDocumentCPF/CNPJobrigatório — CC, NIT, CE ou TI
Instrução de pagamentopixCode, na respostaredirectUrl, alguns segundos depois

A Colômbia é o país que mais exige dado do pagador. Sem nome, telefone, e-mail e documento a rede recusa antes mesmo de criar a cobrança. Colete os quatro na sua tela.

Limites da rede: mínimo COP 10.000 e máximo COP 10.000.000 por transação.

amount continua em centavos, como no BRL. O peso colombiano tem valores altos, então os números ficam grandes: o mínimo de COP 10.000 é 1000000, não 10000.

Exemplo — criar cobrança COP

bash
curl -X POST "https://production.brazilianpix.com/transactions/v2/purchase" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Gómez",
    "email": "carlos@ejemplo.com",
    "phone": "573001234567",
    "amount": 5000000,
    "currency": "COP",
    "description": "Suscripción Pro",
    "responsibleDocument": "11987654321",
    "postbackUrl": "https://seu-dominio.com/webhook"
  }'

Resposta — repare no redirectUrl vazio:

JSON
{
  "id": "17864385245624641191295936",
  "currency": "COP",
  "method": "BANK_TRANSFER",
  "status": "PENDING",
  "amount": 5000000,
  "redirectUrl": "",
  "expiresAt": null,
  "createdAt": "2026-09-02T08:55:24.748Z"
}

Alguns segundos depois, GET /transactions/:id traz o link. Redirecione o comprador para ele.

Como esse dinheiro vira saque

Cash-out em pesos colombianos não existe: todo saque da plataforma sai em BRL, por PIX. O caminho do dinheiro é sempre o mesmo:

  1. O comprador paga e o saldo entra em COP.
  2. A BrazilianHub liquida esse saldo para BRL pela cotação de câmbio do dia.
  3. O valor em BRL passa a aparecer no seu saldo e você saca pelo fluxo normal — POST /withdraws/cash-out, o mesmo de uma conta brasileira.

Você não faz nada no passo 2. Não existe endpoint de conversão, não precisa abrir chamado nem aprovar cotação — a liquidação é operada pela BrazilianHub e o saldo em BRL simplesmente aparece. Do lado da sua integração, a Colômbia é só mais uma moeda de entrada: você cobra em COP e saca em BRL como sempre fez.

O que muda pro seu fluxo de caixa: enquanto o saldo estiver em COP, ele ainda não é sacável — só o saldo em BRL é. Consulte os dois em GET /accounts/balances, que devolve uma linha por moeda, e programe o saque em cima da linha de BRL.