Referência da API

Criar transação (COP)

Cria uma transação de entrada em COP (pesos colombianos). Quatro métodos: BANK_TRANSFER (padrão), PSE, NEQUI e BREB — escolha pelo paymentMethod. Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando currency para "COP". Diferente do PIX, o pagador não copia um código: ele é enviado para a página do banco dele através de um redirectUrl. A instrução NÃO vem nesta resposta — chega alguns segundos depois, por GET /transactions/:id. Conceitos e fluxo completo em Colômbia (COP).

POST/transactions/v2/purchase

Quatro dados do pagador são obrigatórios

responsibleDocument A Colômbia é o país mais exigente: sem name, phone, email e documento do pagador (CC, NIT, CE ou TI) a rede recusa ANTES de criar a cobrança. Colete os quatro na sua tela. E, como na Argentina, o redirectUrl vem VAZIO na criação — busque em GET /transactions/:id até vir preenchido.

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' | 'BREB'opcional

Opcional para currency: COP — default BANK_TRANSFER. PSE é débito online pelo banco do comprador e é o meio dominante no país — quem vende para o público geral colombiano deve oferecê-lo. NEQUI é carteira digital, alcança quem não tem conta bancária. BREB é o instantâneo do banco central. Os quatro devolvem a instrução como redirectUrl por webhook, e a resposta só difere no campo method.

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 do comprador, o meio dominante no país.
# NEQUI e BREB usam o MESMO formato: troque só o paymentMethod.
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",
    "paymentMethod": "PSE",
    "description": "Suscripción Pro",
    "responsibleDocument": "11987654321",
    "responsibleExternalId": "user-1234"
  }'

# A resposta é igual nos quatro: redirectUrl vazio, preenchido no GET.
# Só o campo "method" muda.

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",
    "responsibleExternalId": "user-1234",
    "postbackUrl": "https://seu-dominio.com/webhook"
  }'