> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useduro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment & Invoice Events

> Charge and invoice events, each with a realistic sample payload.

Charge and invoice events. These carry the `invoice` and (via the invoice or the event) the `subscription`, plus its `customer` and `plan`. The shared delivery envelope, headers, and inline-expansion rules are on the [webhooks overview](/webhooks/delivery) and the [event index](/api-reference/webhook-events); every sample below shows the full envelope.

<AccordionGroup>
  <Accordion title="invoice_created" icon="file-invoice">
    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`.

    ```json theme={null}
    {
      "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
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="subscription_payment_success" icon="money-bill-wave">
    Fires when a charge succeeds: a renewal or the first payment at checkout. Carries the `amount` and the completed billing `cycle` number.

    ```json theme={null}
    {
      "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
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="subscription_payment_failed" icon="circle-exclamation">
    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`.

    ```json theme={null}
    {
      "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
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="subscription_payment_recovered" icon="hand-holding-dollar">
    Fires when a previously-failed invoice is charged successfully during dunning. Carries the recovered `amount`.

    ```json theme={null}
    {
      "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
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="subscription_payment_refunded" icon="rotate-left">
    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.

    ```json theme={null}
    {
      "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
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="subscription_payment_action_required" icon="hand">
    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).

    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>