BrazilianHubBrazilianHubdocs

Referência da API

Criar transação (COP)

Cria uma transação de entrada em COP (pesos colombianos). Seis métodos pelo paymentMethod: BANK_TRANSFER (padrão) e PSE (redirect por webhook), NEQUI (push no app Nequi — sem instrução), NEQUI_QR e BREB (QR inline na resposta) e BREB_KEY (chave Bre-B inline). Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando currency para "COP". A instrução chega de um jeito por método (ver abaixo). Conceitos e fluxo completo em Colômbia (COP).

POST/transactions/v2/purchase
Dados do pagador exigidos variam por método
paymentMethod BANK_TRANSFER/PSE exigem name, phone, email e documento (CC, NIT, CE ou TI) — sem os quatro a rede recusa antes de criar, e o redirectUrl chega VAZIO na criação (busque em GET /transactions/:id). NEQUI exige só o phone (10 dígitos, sem +57). NEQUI_QR/BREB/BREB_KEY não pedem dado do pagador — só o valor — e já trazem o QR/chave na própria resposta.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

namestringobrigatório

Nome completo do pagador (máximo 255 caracteres).

Exemplo: Carlos Gómez

emailstringobrigatório

E-mail válido do pagador. Obrigatório na Colômbia — a rede recusa a cobrança sem ele.

Exemplo: carlos@ejemplo.com

phonestringobrigatório

Telefone do pagador com DDI. Obrigatório na Colômbia, ao contrário de MXN e ARS.

Exemplo: 573001234567

amountnumberobrigatório

Valor em centavos de peso colombiano. COP 50.000,00 = 5000000. A rede aceita de COP 10.000 a COP 10.000.000 por transação. Atenção à escala: o mínimo de COP 10.000 é 1000000, não 10000.

Exemplo: 5000000

descriptionstringobrigatório

Descrição curta da transação que aparece no comprovante do pagador.

Exemplo: Suscripción Pro

responsibleDocumentstringobrigatório

Documento do pagador colombiano — CC, NIT, CE ou TI. Obrigatório: a rede identifica o pagador por ele.

Exemplo: 11987654321

responsibleExternalIdstringobrigatório

ID interno do responsável no seu sistema (ex: ID do vendedor, ID da conta).

Exemplo: user-1234

currency'COP'obrigatório

Código da moeda. Para Colômbia use "COP". O amount continua em CENTAVOS. Omitir currency cai no padrão BRL (PIX).

Exemplo: COP

paymentMethod'BANK_TRANSFER' | 'PSE' | 'NEQUI' | 'NEQUI_QR' | 'BREB' | 'BREB_KEY'opcional

Opcional para currency: COP — default BANK_TRANSFER. PSE (débito online pelo banco, o meio dominante) e BANK_TRANSFER entregam a instrução como redirectUrl por webhook. NEQUI (carteira digital) manda um push pro app do comprador — sem QR/link, ele aprova lá. NEQUI_QR e BREB (instantâneo do banco central) trazem um QR inline na resposta (payeeData.qr). BREB_KEY traz uma chave Bre-B inline (payeeData.reference). NEQUI_QR e BREB_KEY são habilitados por conta.

Exemplo: PSE

cpfstringopcional

Não usado em COP — é um documento brasileiro. O documento do pagador colombiano vai em responsibleDocument.

externalIdstringopcional

Sua referência para essa transação. Retornada em GET /transactions/:id?searchBy=externalId e em todo webhook vinculado a essa transação.

Exemplo: pedido-5678

postbackUrlstringopcional

URL de webhook para eventos dessa transação. Se omitido, usa a URL global do dashboard.

Exemplo: https://seu-dominio.com/webhook

Body da requisição

Content-Type: application/json

JSON
{
  "name": "Carlos Gómez",
  "email": "carlos@ejemplo.com",
  "phone": "573001234567",
  "amount": 5000000,
  "currency": "COP",
  "description": "Suscripción Pro",
  "responsibleDocument": "11987654321",
  "responsibleExternalId": "user-1234",
  "externalId": "pedido-5678",
  "postbackUrl": "https://seu-dominio.com/webhook"
}

Respostas

201

Cobrança criada. redirectUrl vem vazio — é o esperado: o link é negociado com a rede colombiana e chega em alguns segundos. Busque em GET /transactions/:id até vir preenchido e então redirecione o comprador. status fica PENDING até o dinheiro cair (webhook cashin.paid).

JSON
{
  "id": "17864385245624641191295936",
  "currency": "COP",
  "method": "BANK_TRANSFER",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 5000000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "redirectUrl": null,
  "expiresAt": null,
  "createdAt": "2026-09-02T08:55:24.748Z",
  "costFee": 150000
}
400

Erro de validação — inclui valor fora da faixa aceita pela rede (COP 10.000 a COP 10.000.000) e falta de phone, email ou documento do pagador.

JSON
{
  "statusCode": 400,
  "message": "The 'phone' field is required for COP transactions.",
  "error": "Bad Request"
}
401

API key inválida ou ausente.

JSON
{ "statusCode": 401, "message": "Unauthorized" }
403

API key sem a permissão createTransaction.

JSON
{ "statusCode": 403, "message": "Forbidden" }

Exemplos

bash
# PSE — débito online pelo banco. Exige name/email/phone/responsibleDocument;
# o redirectUrl chega por webhook. (BANK_TRANSFER usa o mesmo formato.)
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",
    "paymentMethod": "PSE",
    "description": "Suscripción Pro",
    "responsibleDocument": "11987654321",
    "responsibleExternalId": "user-1234"
  }'

# NEQUI     -> só o phone (10 díg, sem +57); NÃO retorna instrução (push no app).
# NEQUI_QR  -> só o amount; retorna payeeData.qr (QR inline) + checkoutUrl.
# BREB      -> só o amount; retorna payeeData.qr (QR inline) + checkoutUrl.
# BREB_KEY  -> só o amount; retorna payeeData.reference (chave) + checkoutUrl.
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",
    "responsibleExternalId": "user-1234",
    "postbackUrl": "https://seu-dominio.com/webhook"
  }'