Referência da API

Criar transação (Pix ou Boleto)

Cria uma transação de entrada em BRL no método híbrido Pix ou Boleto: uma única cobrança que o pagador quita por PIX (na hora) ou por boleto (até o vencimento). Mesmo endpoint do PIX — POST /transactions/v2/purchase — mudando paymentMethod para "PIX_BOLETO". O payload é idêntico ao do boleto e exige o endereço do pagador (boletoAddress). A resposta traz pixCode e boletoDigitableLine; 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

Paga-se só um dos dois trilhos

pixCode A cobrança aceita PIX OU boleto — quando qualquer um é pago, ela é baixada e o outro deixa de valer. A confirmação chega pelo webhook cashin.paid (instantâneo no PIX, até o vencimento no boleto). O valor cai no mesmo saldo do PIX (BRL). Se pixCode ou boletoDigitableLine vierem vazios na criação, faça polling em GET /transactions/:id — aparecem 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'PIX_BOLETO'obrigatório

Para o híbrido use "PIX_BOLETO". No BRL o paymentMethod é obrigatório (os outros são "PIX", "CREDIT_CARD" e "BOLETO").

Exemplo: PIX_BOLETO

boletoAddressobjectobrigatório

Endereço do pagador (exigido pela emissão do boleto). 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 do boleto no formato YYYY-MM-DD. Se omitido, usamos hoje + 3 dias. O PIX segue válido independente disso.

Exemplo: 2026-10-20

descriptionstringobrigatório

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

Exemplo: pix ou 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": "PIX_BOLETO",
  "name": "Maria Souza",
  "email": "maria@exemplo.com",
  "cpf": "12345678901",
  "phone": "11999998888",
  "dueDate": "2026-10-20",
  "description": "pix ou 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 híbrida criada. O pixCode (BR Code copia-e-cola) vem no nível raiz; os dados do boleto vêm no objeto paymentInstruction (boletoDigitableLine, boletoBarcode, boletoUrl, dueDate). Se paymentInstruction vier vazio, busque em GET /transactions/:id até preencher. status fica PENDING até o pagamento cair por qualquer um dos trilhos (webhook cashin.paid). Valores em centavos.

JSON

{
  "id": "17908775406424642135362435",
  "currency": "BRL",
  "method": "PIX_BOLETO",
  "installments": null,
  "externalId": "pedido-5678",
  "status": "PENDING",
  "amount": 5000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "referrerUrl": null,
  "pixCode": "00020126580014br.gov.bcb.pix0136...5204000053039865802BR6009SAO PAULO62070503***6304ABCD",
  "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": "PIX_BOLETO",
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "cpf": "12345678901",
    "phone": "11999998888",
    "dueDate": "2026-10-20",
    "description": "pix ou 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"
    }
  }'