Referência da API

Criar transação (Boleto)

Cria uma transação de entrada em BRL por boleto registrado. Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando paymentMethod para "BOLETO". O boleto registrado exige o endereço do pagador (boletoAddress). A boletoDigitableLine e o boletoBarcode podem vir vazios na criação (registro na Núclea) — busque em GET /transactions/:id até preencherem. Conceitos e fluxo completo em Brasil (BRL).

POST/transactions/v2/purchase

Boleto não é instantâneo

boletoDigitableLine A confirmação chega pelo webhook cashin.paid quando o pagador paga (até o vencimento), igual ao PIX só que não na hora. O valor cai no mesmo saldo do PIX (BRL). Se a linha digitável vier vazia na criação, faça polling em GET /transactions/:id — ela aparece em instantes, após o registro.

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: Maria Souza

emailstringobrigatório

E-mail válido do pagador.

Exemplo: maria@exemplo.com

cpfstringobrigatório

CPF (11) ou CNPJ (14) do pagador. Obrigatório no BRL.

Exemplo: 12345678901

phonestringobrigatório

Telefone do pagador (8 a 12 dígitos).

Exemplo: 11999998888

amountnumberobrigatório

Valor em centavos. R$ 50,00 = 5000.

Exemplo: 5000

paymentMethod'BOLETO'obrigatório

Para boleto use "BOLETO". No BRL o paymentMethod é obrigatório (os outros são "PIX" e "CREDIT_CARD").

Exemplo: BOLETO

boletoAddressobjectobrigatório

Endereço do pagador (exigido pelo boleto registrado). Campos obrigatórios: address (logradouro), district (bairro), city, zipCode (8 dígitos) e uf (2 letras). Opcionais: number, complement.

Exemplo: { "address": "Rua das Flores", "number": "123", "district": "Centro", "city": "São Paulo", "zipCode": "01001000", "uf": "SP" }

dueDatestringopcional

Vencimento no formato YYYY-MM-DD. Se omitido, usamos hoje + 3 dias.

Exemplo: 2026-10-20

descriptionstringobrigatório

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

Exemplo: boleto

responsibleDocumentstringobrigatório

CPF/CNPJ do responsável pela transação (o lojista).

Exemplo: 1234567890

responsibleExternalIdstringobrigatório

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

Exemplo: 123

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

{
  "amount": 5000,
  "paymentMethod": "BOLETO",
  "name": "Maria Souza",
  "email": "maria@exemplo.com",
  "cpf": "12345678901",
  "phone": "11999998888",
  "dueDate": "2026-10-20",
  "description": "boleto",
  "responsibleDocument": "1234567890",
  "responsibleExternalId": "123",
  "boletoAddress": {
    "address": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "district": "Centro",
    "city": "São Paulo",
    "zipCode": "01001000",
    "uf": "SP"
  }
}

Respostas

201

Cobrança criada. Os dados do boleto vêm no objeto paymentInstruction (boletoDigitableLine, boletoBarcode, boletoUrl, dueDate). O campo boletoDigitableLine do nível raiz costuma vir null na criação (é a instrução imediata do trilho; no boleto ela chega dentro de paymentInstruction). Se paymentInstruction vier vazio, busque em GET /transactions/:id até preencher. status fica PENDING até o pagamento cair (webhook cashin.paid). Valores em centavos (amount: 5000 = R$ 50,00).

JSON

{
  "id": "17908775406424642135362435",
  "currency": "BRL",
  "method": "BOLETO",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 5000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "boletoDigitableLine": null,
  "paymentInstruction": {
    "type": "BOLETO",
    "dueDate": "2026-10-10T03:00:00.000Z",
    "boletoUrl": null,
    "boletoBarcode": "34191987700000050001790001010435100479102015000",
    "boletoDigitableLine": "34191.79001 01043.510047 91020.150008 1 98770000005000"
  },
  "expiresAt": null,
  "createdAt": "2026-10-01T12:00:00.000Z",
  "costFee": 100
}

400

Erro de validação — inclui endereço do pagador incompleto (logradouro, bairro, cidade, CEP de 8 dígitos e UF de 2 letras) e campos obrigatórios ausentes.

JSON

{
  "statusCode": 400,
  "message": "O endereço do pagador é obrigatório para boleto.",
  "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

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 '{
    "amount": 5000,
    "paymentMethod": "BOLETO",
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "cpf": "12345678901",
    "phone": "11999998888",
    "dueDate": "2026-10-20",
    "description": "boleto",
    "responsibleDocument": "1234567890",
    "responsibleExternalId": "123",
    "boletoAddress": {
      "address": "Rua das Flores",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "São Paulo",
      "zipCode": "01001000",
      "uf": "SP"
    }
  }'