Referência da API

Criar fatura

Cria uma Invoice (cobrança individual). Pode ser:

Avulsa sem customerId — Invoice "pública", qualquer pessoa com a hostedUrl paga.
Vinculada a Customer — passe customerId. Notificações automáticas são enviadas.
Vinculada a Subscription — passe subscriptionId (uso interno: o cron de billing usa isso; raramente você cria assim via API).

Valores em centavos. A hostedUrl é gerada automaticamente. Moeda: a fatura nasce na moeda da sua conta e a guarda. Não é campo do corpo — é congelada na emissão de propósito: se a moeda da conta mudar depois, uma fatura já emitida continua sendo cobrada na moeda em que nasceu. O campo currency volta na resposta.

POST/v2/invoices

Soma dos items precisa bater com amount

items Se você enviar items[], a soma dos totalPrice (em centavos) deve bater exatamente com amount. E totalPrice de cada item deve ser quantity * unitPrice. Se não bater, a API rejeita com 400.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

customerIdstring (UUID) | nullopcional

UUID do Customer dono da Invoice. null ou ausente = Invoice pública. Quando presente, ativa envio automático de notificações.

Exemplo: c8a5f4d2-...

subscriptionIdstring (UUID)opcional

UUID da Subscription que gerou essa Invoice. Uso interno (o cron de billing seta isso). Se enviado, o customerId precisa bater com o da Subscription.

Exemplo: sub_abc123-...

descriptionstringobrigatório

Descrição da cobrança. Exibida no hostedUrl ao cliente final e em notificações.

Exemplo: Setup inicial + 3 meses de consultoria

amountnumber (integer, centavos)obrigatório

Valor total da cobrança, em centavos. Se items for enviado, deve bater com a soma de totalPrice.

Exemplo: 49700

itemsInvoiceItem[]opcional

Linhas detalhadas. Cada item: description, quantity (int >= 1), unitPrice (centavos), totalPrice (centavos, deve ser quantity * unitPrice). A soma dos totalPrice precisa bater com amount.

Exemplo: [{ "description": "Setup", "quantity": 1, "unitPrice": 19700, "totalPrice": 19700 }]

dueDatestring (ISO 8601)obrigatório

Data de vencimento. Depois disso a Invoice vira OVERDUE.

Exemplo: 2026-06-15T00:00:00.000Z

expiresAtstring (ISO 8601)opcional

Data em que a hostedUrl para de aceitar pagamento (Invoice vira EXPIRED). Default: dueDate + 30 dias. Não pode ser antes de dueDate.

Exemplo: 2026-07-15T00:00:00.000Z

lateFeeType'NONE' | 'FIXED' | 'PERCENTAGE'opcional

Tipo de multa aplicada em atraso. Default: NONE.

Exemplo: FIXED

lateFeeValuenumber (integer)opcional

Valor da multa. FIXED: em centavos (500 = R$ 5,00). PERCENTAGE: percentual cru (2 = 2%; máximo 100). Obrigatório se lateFeeType != NONE.

Exemplo: 500

interestRatePerMonthnumber (percentual, aceita decimais)opcional

Juros mensais aplicados proporcionalmente por dia de atraso. Percentual cru ao mês (1 = 1% ao mês; aceita frações como 1.5; máximo 100). Default: 0.

Exemplo: 1

paymentMethodsInvoicePaymentMethod[]opcional

Métodos aceitos no checkout: PIX, BOLETO (ou ambos). Default: ['PIX']. Para boleto, o Customer da fatura precisa ter endereço completo cadastrado.

Exemplo: ["PIX", "BOLETO"]

successUrlstring (URL)opcional

URL para redirecionar o cliente após pagamento bem-sucedido na hostedUrl.

Exemplo: https://app.exemplo.com/sucesso

failureUrlstring (URL)opcional

URL para redirecionar o cliente em caso de falha no pagamento.

Exemplo: https://app.exemplo.com/erro

notificationConfigobjectopcional

Configuração de notificações automáticas. Se ausente, default: envia e-mail de criação se houver customerId com email. Use { onCreate: false } pra desabilitar e-mail de criação.

Exemplo: { "onCreate": true }

metadataobjectopcional

JSON arbitrário pra anexar dados do seu sistema.

Exemplo: { "orderId": "pedido-9876" }

Body da requisição

Content-Type: application/json

JSON

// Invoice avulsa com customer e items:
{
  "customerId": "c8a5f4d2-...",
  "description": "Setup inicial + 3 meses de consultoria",
  "amount": 49700,
  "dueDate": "2026-06-15T00:00:00.000Z",
  "items": [
    { "description": "Taxa de setup", "quantity": 1, "unitPrice": 19700, "totalPrice": 19700 },
    { "description": "Consultoria mensal", "quantity": 3, "unitPrice": 10000, "totalPrice": 30000 }
  ],
  "lateFeeType": "FIXED",
  "lateFeeValue": 500,
  "interestRatePerMonth": 1,
  "paymentMethods": ["PIX"]
}

// Invoice pública (sem customer):
{
  "description": "Mensalidade do plano Pro",
  "amount": 4900,
  "dueDate": "2026-06-15T00:00:00.000Z"
}

Respostas

201

Invoice criada com status PENDING. hostedUrl gerada automaticamente. Se houver customerId com email e a notificação onCreate estiver habilitada, um e-mail de criação foi enfileirado.

JSON

{
  "id": "inv_111aaa",
  "createdByUserId": "u-1234",
  "customerId": "c8a5f4d2-...",
  "subscriptionId": null,
  "status": "PENDING",
  "description": "Setup inicial + 3 meses de consultoria",
  "items": [
    { "description": "Taxa de setup", "quantity": 1, "unitPrice": 19700, "totalPrice": 19700 },
    { "description": "Consultoria mensal", "quantity": 3, "unitPrice": 10000, "totalPrice": 30000 }
  ],
  "amount": 49700,
  "amountPaid": 0,
  "refundedAmount": null,
  "dueDate": "2026-06-15T00:00:00.000Z",
  "expiresAt": "2026-07-15T00:00:00.000Z",
  "paidAt": null,
  "canceledAt": null,
  "refundedAt": null,
  "lateFeeType": "FIXED",
  "lateFeeValue": 500,
  "interestRatePerMonth": 1,
  "paymentMethods": ["PIX"],
  "hostedUrl": "https://checkout.ihubplay.com/i/inv_111aaa",
  "successUrl": null,
  "failureUrl": null,
  "metadata": null,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T14:32:01.923Z"
}

400

Validação falhou. Causas comuns: soma dos items != amount, dueDate inválida, expiresAt antes de dueDate, lateFeeValue ausente com lateFeeType != NONE.

JSON

{
  "status": 400,
  "error": "Soma dos items (50000) nao bate com amount (49700)"
}

404

Customer ou Subscription não encontrados.

JSON

{ "status": 404, "error": "Customer nao encontrado" }

Exemplos

cURL

curl -X POST "https://api.ihubplay.com/v2/invoices" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c8a5f4d2-...",
    "description": "Mensalidade Setembro",
    "amount": 4900,
    "dueDate": "2026-09-15T00:00:00.000Z"
  }'

JavaScript

const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");

const res = await fetch("https://api.ihubplay.com/v2/invoices", {
  method: "POST",
  headers: { Authorization: `Basic ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    customerId: "c8a5f4d2-...",
    description: "Setup inicial",
    amount: 49700,                  // R$ 497 em centavos
    dueDate: "2026-06-15T00:00:00.000Z",
    lateFeeType: "FIXED",
    lateFeeValue: 500,              // R$ 5,00 em centavos
    interestRatePerMonth: 1,        // 1% ao mês
  }),
});

const inv = await res.json();
console.log("URL pública:", inv.hostedUrl);