Payment & Invoice Events

invoice_created

Fires when a renewal invoice is generated at the start of a billing cycle, before the charge is attempted. Carries the amount (minor units) alongside the invoice and subscription.

{
  "id": "evt_01hkbz5invcrt00000000000000",
  "type": "invoice_created",
  "createdAt": "2026-07-28T09:00:00.000Z",
  "data": {
    "amount": 500000,
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "open",
      "periodStart": "2027-06-28T09:00:00.000Z",
      "periodEnd": "2028-06-28T09:00:00.000Z"
    },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_payment_success

Fires when a charge succeeds: a renewal or the first payment at checkout. Carries the amount and the completed billing cycle number.

{
  "id": "evt_01hkbz5paysucc0000000000000",
  "type": "subscription_payment_success",
  "createdAt": "2026-06-28T09:00:00.000Z",
  "data": {
    "amount": 500000,
    "cycle": 1,
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "paid",
      "periodStart": "2026-06-28T09:00:00.000Z",
      "periodEnd": "2027-06-28T09:00:00.000Z"
    },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_payment_failed

Fires when a charge fails. Carries the failureCode, the dunning action decided (for example retry_scheduled, request_card_update, or dunning_disabled), and, when another attempt is scheduled, the nextAttemptAt.

{
  "id": "evt_01hkbz5payfail0000000000000",
  "type": "subscription_payment_failed",
  "createdAt": "2026-07-28T09:00:00.000Z",
  "data": {
    "failureCode": "insufficient_funds",
    "action": "retry_scheduled",
    "nextAttemptAt": "2026-07-29T09:00:00.000Z",
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "open",
      "periodStart": "2027-06-28T09:00:00.000Z",
      "periodEnd": "2028-06-28T09:00:00.000Z"
    },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "past_due",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_payment_recovered

Fires when a previously-failed invoice is charged successfully during dunning. Carries the recovered amount.

{
  "id": "evt_01hkbz5payrecv0000000000000",
  "type": "subscription_payment_recovered",
  "createdAt": "2026-07-29T09:00:00.000Z",
  "data": {
    "amount": 500000,
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "paid",
      "periodStart": "2027-06-28T09:00:00.000Z",
      "periodEnd": "2028-06-28T09:00:00.000Z"
    },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_payment_refunded

Fires when a paid invoice is refunded, via POST /v1/invoices/{id}/refund, or reconciled from a Nomba reversal webhook (source: "webhook"). Carries the refunded amount, the rail, and the gateway transactionId when present. A merchant-initiated refund also echoes any reason you sent.

{
  "id": "evt_01hkbz5refund00000000000000",
  "type": "subscription_payment_refunded",
  "createdAt": "2026-06-30T09:00:00.000Z",
  "data": {
    "amount": 500000,
    "rail": "card",
    "transactionId": "9f2c1b7a-2d3e-4f5a-8b9c-0d1e2f3a4b5c",
    "reason": "duplicate charge",
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "paid",
      "periodStart": "2026-06-28T09:00:00.000Z",
      "periodEnd": "2027-06-28T09:00:00.000Z"
    },
    "subscription": {
      "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
      "status": "active",
      "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "currentPeriodStart": "2026-06-28T09:00:00.000Z",
      "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
      "trialEndsAt": null
    },
    "customer": {
      "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
      "email": "ada@example.com",
      "name": "Ada Lovelace",
      "phone": "+2348012345678"
    },
    "plan": {
      "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
      "name": "Pro Annual",
      "amount": 500000,
      "currency": "NGN",
      "interval": "year",
      "intervalCount": 1
    }
  }
}

subscription_payment_action_required

Fires when dunning decides the customer must update their card before Duro can charge again. Carries the invoice and a reason; no subscription is expanded on this event (only the invoice reference is present in the raw event).

{
  "id": "evt_01hkbz5actreq00000000000000",
  "type": "subscription_payment_action_required",
  "createdAt": "2026-07-30T09:00:00.000Z",
  "data": {
    "reason": "card_expired",
    "invoice": {
      "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
      "amount": 500000,
      "currency": "NGN",
      "status": "open",
      "periodStart": "2027-06-28T09:00:00.000Z",
      "periodEnd": "2028-06-28T09:00:00.000Z"
    }
  }
}