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 tiver um adquirente COP configurado. A moeda da transação precisa casar com a do adquirente.

Os quatro meios de pagamento

A Colômbia aceita quatro trilhos de entrada. Todos usam o mesmo endpoint e entregam a instrução do mesmo jeito — um redirectUrl que chega por webhook. Muda só o paymentMethod:

`paymentMethod`	O que é	Quando usar
`"BANK_TRANSFER"`	transferência bancária (padrão)	genérico, aceita qualquer banco
`"PSE"`	débito online pelo banco do comprador	o meio dominante no país
`"NEQUI"`	carteira digital	comprador sem conta bancária tradicional
`"BREB"`	instantâneo do banco central	o "Pix colombiano", recém-lançado

Omitir paymentMethod usa BANK_TRANSFER. Se você vende para o público geral colombiano, ofereça o PSE — é o que a maioria espera encontrar.

Os quatro exigem os mesmos dados do pagador (name, phone, email e responsibleDocument) e respeitam a mesma faixa da rede, de COP 10.000 a COP 10.000.000.

Exemplos — um por método

PSE — o comprador escolhe o banco na página para a qual você o envia:

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"
}

Nequi — carteira digital; o pagador autoriza no app:

JSON

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

Bre-B — instantâneo, liquida em segundos:

JSON

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

A resposta é idêntica nos quatro: status: "PENDING" com redirectUrl vazio, preenchido alguns segundos depois via GET /transactions/:id. Só o campo method muda.

A taxa pode ser diferente por método. Confira o preço de cada um no painel antes de ofertar os quatro.

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.

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://api.ihubplay.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:

O comprador paga e o saldo entra em COP.
A iHubGames 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 iHubGames 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.