Invoices

Invoice webhook events and example payloads.

Invoice webhooks track invoice creation, updates, payment, and expiry.

Use these events to keep invoice state in sync with your system.

Field descriptions

Invoice webhook events use data.invoice.

Some invoice events also include data.payments.

Field	Type	Description
data.invoice.id	string	Unique invoice identifier.
data.invoice.reference	string	Your invoice reference.
data.invoice.amount	string	Invoice amount as a decimal string.
data.invoice.amountPaid	string	Amount paid so far.
data.invoice.currency	string	Invoice currency.
data.invoice.status	string	Invoice payment status.
data.invoice.isRefunded	boolean	Whether the invoice has been refunded.
data.invoice.state	'open' | 'closed'	Invoice state.
data.invoice.description	string | null	Optional invoice description.
data.invoice.expiresAt	string | null	Expiry timestamp.
data.invoice.paidAt	string | null	Paid timestamp when available.
data.invoice.periodStart	string | null	Billing period start when applicable.
data.invoice.periodEnd	string | null	Billing period end when applicable.
data.invoice.nextPaymentDate	string | null	Next scheduled payment date.
data.invoice.metadata	object | null	Custom metadata.
data.invoice.successUrl	string	Redirect URL used after success.
data.invoice.cancelUrl	string	Redirect URL used after cancellation.
data.invoice.customer	object	Customer information.
data.invoice.customer.telegramId	string | null	Customer Telegram ID when available.
data.invoice.createdAt	string	Creation timestamp.
data.invoice.updatedAt	string	Last update timestamp.
data.payments	array | null	Payment activity linked to the invoice.

Invoice payloads include metadata, successUrl, cancelUrl, and billing period fields even when the values are null.

Events

• invoice.created
• invoice.updated
• invoice.paid
• invoice.expired

invoice.created

Sent when an invoice is created.

Use this event to create an invoice record or start an expiry timer.

{
  "event": "invoice.created",
  "data": {
    "invoice": {
      "id": "inv_123456789_abcdef",
      "reference": "INV-2024-001",
      "amount": "1000.00",
      "amountPaid": "0.00",
      "currency": "NGN",
      "status": "pending",
      "isRefunded": false,
      "state": "open",
      "description": "Invoice for services rendered",
      "expiresAt": "2024-02-15T10:30:00.000Z",
      "paidAt": null,
      "periodStart": null,
      "periodEnd": null,
      "nextPaymentDate": null,
      "metadata": {
        "orderId": "ORDER-2024-001"
      },
      "successUrl": "https://example.com/invoice/inv-2024-001",
      "cancelUrl": "https://example.com/invoice/inv-2024-001",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe",
        "telegramId": null
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "payments": null
  }
}

invoice.updated

Sent when an invoice receives a payment or changes state.

Use this event to refresh totals and partial payment state.

{
  "event": "invoice.updated",
  "data": {
    "invoice": {
      "id": "inv_123456789_abcdef",
      "reference": "INV-2024-001",
      "amount": "1000.00",
      "amountPaid": "500.00",
      "currency": "NGN",
      "status": "partial",
      "isRefunded": false,
      "state": "open",
      "description": "Invoice for services rendered",
      "expiresAt": "2024-02-15T10:30:00.000Z",
      "paidAt": null,
      "periodStart": null,
      "periodEnd": null,
      "nextPaymentDate": null,
      "metadata": {
        "orderId": "ORDER-2024-001"
      },
      "successUrl": "https://example.com/invoice/inv-2024-001",
      "cancelUrl": "https://example.com/invoice/inv-2024-001",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe",
        "telegramId": null
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "payments": [
      {
        "sessionId": "cs_123456789_abcdef",
        "sessionReference": "ORDER-2024-001",
        "status": "confirmed",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "confirmedAt": "2024-01-15T10:35:00.000Z"
      }
    ]
  }
}

invoice.paid

Sent when an invoice is fully paid.

Use this event to fulfill the order.

{
  "event": "invoice.paid",
  "data": {
    "invoice": {
      "id": "inv_123456789_abcdef",
      "reference": "INV-2024-001",
      "amount": "1000.00",
      "amountPaid": "1000.00",
      "currency": "NGN",
      "status": "paid",
      "isRefunded": false,
      "state": "open",
      "description": "Invoice for services rendered",
      "expiresAt": "2024-02-15T10:30:00.000Z",
      "paidAt": "2024-01-15T10:35:00.000Z",
      "periodStart": null,
      "periodEnd": null,
      "nextPaymentDate": null,
      "metadata": {
        "orderId": "ORDER-2024-001"
      },
      "successUrl": "https://example.com/invoice/inv-2024-001",
      "cancelUrl": "https://example.com/invoice/inv-2024-001",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe",
        "telegramId": null
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "payments": [
      {
        "sessionId": "cs_123456789_abcdef",
        "sessionReference": "ORDER-2024-001",
        "status": "confirmed",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "confirmedAt": "2024-01-15T10:35:00.000Z"
      }
    ]
  }
}

invoice.expired

Sent when an invoice expires.

Use this event to close unpaid invoices.

{
  "event": "invoice.expired",
  "data": {
    "invoice": {
      "id": "inv_123456789_abcdef",
      "reference": "INV-2024-001",
      "amount": "1000.00",
      "amountPaid": "0.00",
      "currency": "NGN",
      "status": "pending",
      "isRefunded": false,
      "state": "closed",
      "description": "Invoice for services rendered",
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "paidAt": null,
      "periodStart": null,
      "periodEnd": null,
      "nextPaymentDate": null,
      "metadata": {
        "orderId": "ORDER-2024-001"
      },
      "successUrl": "https://example.com/invoice/inv-2024-001",
      "cancelUrl": "https://example.com/invoice/inv-2024-001",
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe",
        "telegramId": null
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    "payments": null
  }
}