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 comstatus: "PENDING"e o campo vazio — é o comportamento normal, não é erro. Faça polling emGET /transactions/:idaté 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:
paymentMethod | O 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 Nequi | QR inline na resposta (qr) |
"BREB" | instantâneo do banco central — QR Bre-B | QR inline na resposta (qr) |
"BREB_KEY" | transferência para uma chave Bre-B | chave inline na resposta (reference) |
Omitir
paymentMethodusaBANK_TRANSFER.NEQUI_QReBREB_KEYsão habilitados por conta — se a sua não tiver, a criação volta400.
Dados do pagador por método:
BANK_TRANSFER/PSE: exigemname,phone,emaileresponsibleDocument(CC/NIT/CE/TI).NEQUI: exige só ophonedo comprador — 10 dígitos, sem +57 (ex.:3001234567; com +57/espaços/traços a rede recusa com400).name/email/responsibleDocumentsã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:
{
"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:
{
"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:
{
"amount": 5000000,
"currency": "COP",
"paymentMethod": "BREB"
}
Resposta (resumida):
{
"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:
{
"amount": 5000000,
"currency": "COP",
"paymentMethod": "BREB_KEY"
}
Resposta (resumida):
{
"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_QReBREB_KEYsão habilitados por conta — se a sua não tiver, a criação volta400. 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
| Campo | BRL (PIX) | COP (Transferência) |
|---|---|---|
currency | "BRL" (padrão) | "COP" (obrigatório) |
paymentMethod | obrigatório ("PIX") | opcional — default BANK_TRANSFER |
name | obrigatório | obrigatório |
email | opcional | obrigatório |
phone | obrigatório | obrigatório |
responsibleDocument | CPF/CNPJ | obrigatório — CC, NIT, CE ou TI |
| Instrução de pagamento | pixCode, na resposta | redirectUrl, 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.
amountcontinua 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ão10000.
Exemplo — criar cobrança COP
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:
{
"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:
- O comprador paga e o saldo entra em COP.
- A BrazilianHub liquida esse saldo para BRL pela cotação de câmbio do dia.
- 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.