Financeiro da plataforma

Esta pagina trata da cobranca do Minstrel para a sua organizacao: o que voce paga pelo uso da plataforma. Nao confundir com as cobrancas que voce faz aos seus clientes, que estao em Transacoes e Assinaturas.

Tres regras valem para tudo aqui:

• So a producao e cobrada. O uso do sandbox aparece apenas como informacao.
• A conta e da organizacao. As rotas ignoram o ambiente da credencial: uma chave de sandbox ve o mesmo financeiro que uma de producao.
• A API e somente leitura (escopo billing:read). O fechamento do mes e feito pelo Minstrel, nunca a pedido do cliente.

O que e cobrado

A fatura tem uma linha por item do plano:

A conta de cada linha fecha na calculadora: quantity vezes unitAmount da amount. A excecao e o volume, cobrado em percentual: ali quantity e o volume em centavos, unitAmount e nulo e rateBps traz a taxa. Item com preco zero no seu plano nao aparece na fatura; a mensalidade aparece sempre, e a linha de transacoes aparece mesmo sem excedente, para mostrar quanto da franquia foi usado.

Como cada item e contado

• Transacao aprovada conta pelo instante da aprovacao, nao da criacao: uma venda criada as 23h59 do dia 31 e aprovada a 00h01 do dia 1 cai no mes da aprovacao, e nunca em dois meses.
• Estorno, cancelamento e chargeback nao descontam. A cobranca e pela aprovacao: uma venda aprovada e depois estornada ou cancelada continua contando, com o valor integral no volume.
• Tentativa extra e cada tentativa alem da primeira dentro do mesmo pagamento (fallback) e cada cobranca de fatura alem da primeira (retentativa), no instante em que aconteceu. A linha mostra as duas origens em fallbacks e retries.
• Analise antifraude conta toda avaliacao, menos as que o provedor nao conseguiu fazer (recomendacao error).

O mes de cobranca

• O mes segue o calendario de Brasilia (UTC-3): vira a meia-noite do dia 1, e nao a meia-noite UTC.
• A fatura do mes e numerada MNS-AAAA-MM e fecha depois que o mes termina, passada uma folga de 2 horas para as autorizacoes dos ultimos segundos. Fatura fechada nunca e recalculada.
• O vencimento e o dia dueDay do contrato no mes seguinte ao uso. Dia que nao existe no mes (31 em abril) cai no ultimo dia.
• No primeiro mes, a mensalidade e a franquia sao proporcionais aos dias de contrato, contando o dia da contratacao. O arredondamento e feito uma unica vez, meio centavo para cima.

Exemplo

Um plano de exemplo com mensalidade de R$ 490,00, 2.000 transacoes inclusas, R$ 0,09 por transacao excedente, R$ 0,02 por tentativa extra, R$ 0,35 por analise antifraude e sem taxa sobre volume. Num mes com 2.450 transacoes aprovadas, 80 fallbacks, 40 retentativas e 300 analises:

Se o contrato tivesse comecado no dia 10 de um mes de 31 dias, o primeiro mes teria 22 dias de contrato: mensalidade de R$ 347,74 (490,00 x 22 / 31) e franquia de 1.419 transacoes.

Resumo do mes

curl http://localhost:3333/v1/platform-billing/overview \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

A fatura parcial usa o mesmo calculo do fechamento: o numero que voce acompanha durante o mes e exatamente o que fecha no dia 1. A projecao (current.projection) estende o uso ate o fim do mes no ritmo medio ja observado, com base de pelo menos um dia - nas primeiras horas, meia duzia de transacoes multiplicadas pelo mes inteiro dariam um numero absurdo. Se o contrato comecou no meio do mes, o ritmo e medido a partir do dia da contratacao.

Sem plano cadastrado para a organizacao, pricing e current vem null.

Faturas

curl "http://localhost:3333/v1/platform-billing/invoices?status=overdue" \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Lista as faturas mensais da mais recente para a mais antiga, com limit (1 a 100, padrao 24) e startingAfter (id da ultima fatura da pagina anterior).

Uma fatura que vence hoje ainda pode ser paga ate o fim do dia. O filtro status=overdue inclui a fatura em aberto cujo vencimento ja passou, mesmo que a rotina que marca as vencidas ainda nao tenha rodado.

GET /v1/platform-billing/invoices/:id traz as linhas do calculo e, enquanto houver valor a pagar, as instrucoes de pagamento em paymentInstructions: linha digitavel do boleto e Pix copia e cola. O campo vem null quando nao ha instrucoes registradas para a fatura. Fora de producao, as instrucoes sao ficticias e vem marcadas com sample: true - servem para testar a tela de pagamento e nao recebem dinheiro: nao pague.

{
  "object": "platform_invoice",
  "id": "pinv_01HQ...",
  "number": "MNS-2026-09",
  "status": "open",
  "currency": "BRL",
  "periodStart": "2026-09-01T03:00:00.000Z",
  "periodEnd": "2026-10-01T03:00:00.000Z",
  "dueDate": "2026-10-20T00:00:00.000Z",
  "subtotal": 63790,
  "discount": 0,
  "total": 63790,
  "paidAt": null,
  "issuedAt": "2026-10-01T05:00:00.000Z",
  "lines": [
    { "kind": "monthly_fee", "description": "Mensalidade do plano Growth", "quantity": 1, "unitAmount": 49000, "rateBps": null, "amount": 49000 },
    { "kind": "transactions", "description": "Transacoes aprovadas acima da franquia (2000 inclusas)", "quantity": 450, "unitAmount": 9, "rateBps": null, "amount": 4050, "used": 2450, "included": 2000 },
    { "kind": "extra_attempts", "description": "Tentativas extras (retentativas e fallback para outro adquirente)", "quantity": 120, "unitAmount": 2, "rateBps": null, "amount": 240, "fallbacks": 80, "retries": 40 },
    { "kind": "antifraud", "description": "Analises antifraude", "quantity": 300, "unitAmount": 35, "rateBps": null, "amount": 10500 }
  ],
  "paymentInstructions": {
    "sample": true,
    "notice": "Instrucoes ficticias de exemplo (ambiente de desenvolvimento): nao pague. Em producao, o boleto e o Pix sao emitidos pelo banco cobrador da Minstrel.",
    "boleto": { "digitableLine": "00090.00000 ...", "barcode": "0009..." },
    "pix": { "copyPaste": "000201...", "key": "exemplo@minstrel.invalid" }
  }
}

periodEnd e exclusivo: e o inicio do mes seguinte. Datas de periodo estao em UTC e correspondem a meia-noite de Brasilia.