Skip to main content
Este evento é publicado quando uma tentativa de pagamento de uma fatura falha. Isso pode acontecer por diversas razões — cartão recusado, saldo insuficiente, método de pagamento expirado, ou um boleto que não foi pago antes do vencimento. Uma falha de pagamento de fatura é um precursor da degradação da assinatura. Se o problema não for resolvido (seja por retentativas automáticas ou intervenção manual), a assinatura eventualmente transicionará para o status PAST_DUE, disparando um evento separado subscription.past_due.
O campo paidAt será null neste evento, já que o pagamento não foi bem-sucedido. O status será PAYMENT_FAILED. Note que o provedor de pagamento pode automaticamente retentar pagamentos falhos — este evento representa uma única tentativa falha, não necessariamente uma falha terminal.
Ao tratar este evento, considere notificar a organização imediatamente para que possam atualizar seu método de pagamento antes que a assinatura se torne inadimplente. Inclua a informação do paymentMethod na notificação para que saibam qual método de pagamento falhou. Evite enviar notificações duplicadas deduplicando pelo invoiceId.

​
Detalhes do Evento

PropriedadeValor
Typeinvoice.payment_failed

​
Schema do Payload

​
invoiceId
string (UUID v7)
required
Identificador da fatura.
​
organizationId
string (UUID v7)
required
FK para Organization.
​
subscriptionId
string (UUID v7)
FK para Subscription.
​
externalRef
string
required
Referência externa da fatura.
​
type
string
required
Tipo da fatura: PLAN ou FEE.
​
paymentMethod
string
Método de pagamento: CARD ou BOLETO.
​
card
object
Detalhes do cartão: {brand, last4, expMonth, expYear}.
​
boleto
object
Detalhes do boleto: {url}.
​
currency
string
required
Código da moeda (USD, BRL, EUR).
​
totalAmount
integer
required
Total em centavos.
​
discountAmount
integer
required
Desconto em centavos.
​
payableAmount
integer
required
Valor a pagar em centavos.
​
discounts
array
required
Descontos aplicados.
​
lines
array
required
Itens da fatura.
​
status
string
required
Status da fatura.
​
issuedAt
string (ISO 8601)
required
Data de emissão.
​
dueDate
string (ISO 8601)
required
Data de vencimento.
​
paidAt
string (ISO 8601)
Timestamp do pagamento.
​
createdAt
string (ISO 8601)
required
Timestamp de criação.
​
updatedAt
string (ISO 8601)
required
Timestamp da última atualização.
{
  "specversion": "1.0",
  "type": "invoice.payment_failed",
  "id": "evt_0195f3a2-8c00-7d4e-b803-4d5e6f7a8b9c",
  "time": "2026-03-25T14:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "invoiceId": "0195f3a2-8c00-7d4e-b803-4d5e6f7a8b9c",
    "organizationId": "0195f3a2-8c00-7d4e-b801-1a2b3c4d5e6f",
    "subscriptionId": "0195f3a2-8c00-7d4e-b802-2b3c4d5e6f7a",
    "externalRef": "in_abc123",
    "type": "PLAN",
    "paymentMethod": "CARD",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2027
    },
    "boleto": null,
    "currency": "BRL",
    "totalAmount": 4900,
    "discountAmount": 0,
    "payableAmount": 4900,
    "discounts": [],
    "lines": [
      {
        "description": "Pro Plan — Monthly",
        "quantity": 1,
        "unitAmount": 4900,
        "amount": 4900
      }
    ],
    "status": "PAYMENT_FAILED",
    "issuedAt": "2026-03-01T00:00:00Z",
    "dueDate": "2026-03-10T00:00:00Z",
    "paidAt": null,
    "createdAt": "2026-03-01T00:00:00Z",
    "updatedAt": "2026-03-25T14:00:00Z"
  }
}