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).
/transactions/v2/purchasepaymentMethod 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órioNome completo do pagador (máximo 255 caracteres).
Exemplo: Carlos Gómez
emailstringobrigatórioE-mail válido do pagador. Obrigatório na Colômbia — a rede recusa a cobrança sem ele.
Exemplo: carlos@ejemplo.com
phonestringobrigatórioTelefone do pagador com DDI. Obrigatório na Colômbia, ao contrário de MXN e ARS.
Exemplo: 573001234567
amountnumberobrigatórioValor 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órioDescrição curta da transação que aparece no comprovante do pagador.
Exemplo: Suscripción Pro
responsibleDocumentstringobrigatórioDocumento do pagador colombiano — CC, NIT, CE ou TI. Obrigatório: a rede identifica o pagador por ele.
Exemplo: 11987654321
responsibleExternalIdstringobrigatórioID interno do responsável no seu sistema (ex: ID do vendedor, ID da conta).
Exemplo: user-1234
currency'COP'obrigatórioCó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'opcionalOpcional 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
cpfstringopcionalNão usado em COP — é um documento brasileiro. O documento do pagador colombiano vai em responsibleDocument.
externalIdstringopcionalSua 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
postbackUrlstringopcionalURL 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
{
"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
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).
{
"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
}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.
{
"statusCode": 400,
"message": "The 'phone' field is required for COP transactions.",
"error": "Bad Request"
}API key inválida ou ausente.
{ "statusCode": 401, "message": "Unauthorized" }API key sem a permissão createTransaction.
{ "statusCode": 403, "message": "Forbidden" }Exemplos
# 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.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"
}'