> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/webhooks/readme/invoices.md). # Invoices Invoice webhook events and example payloads. Invoice webhooks track invoice payments, updates, and expiry. Use these events to keep invoice state in sync with your system. ### Field descriptions Invoice webhook events use `data.invoice` and `data.payments`. | Field | Type | Description | | ---------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------ | | `data.invoice.id` | `string` | Unique invoice identifier. | | `data.invoice.reference` | `string` | Your invoice reference. | | `data.invoice.description` | `string \| null` | Optional description or notes for the invoice. | | `data.invoice.status` | `string` | Payment status of the invoice. See each event below. | | `data.invoice.state` | `'open' \| 'closed'` | `open` while the invoice accepts payment, `closed` once it is final. | | `data.invoice.isRefunded` | `boolean` | Whether the invoice has been refunded. When `true`, `status` keeps the original payment status. | | `data.invoice.amount` | `string` | Total invoice amount, as a decimal string. Equals the sum of all line totals. | | `data.invoice.amountPaid` | `string` | Amount paid so far, as a decimal string. | | `data.invoice.currency` | `string` | Invoice currency, such as `NGN` or `USD`. | | `data.invoice.items` | `array` | Invoice line items. | | `data.invoice.items[].id` | `string` | Line item identifier. | | `data.invoice.items[].name` | `string` | Line item name. | | `data.invoice.items[].description` | `string \| null` | Line item description. | | `data.invoice.items[].unit` | `string \| null` | Unit label, such as `seats`. | | `data.invoice.items[].quantity` | `string` | Quantity, as a decimal string. | | `data.invoice.items[].unitPrice` | `string` | Price per unit, as a decimal string. | | `data.invoice.items[].lineTotal` | `string` | Quantity times unit price, as a decimal string. | | `data.invoice.customer` | `object` | Customer details: `id`, `email`, `phone`, `firstName`, `lastName`, `telegramId`, and `metadata`. | | `data.invoice.successUrl` | `string` | Where the customer is sent after paying. | | `data.invoice.cancelUrl` | `string` | Where the customer is sent after cancelling. | | `data.invoice.metadata` | `object \| null` | Your custom key-value data. | | `data.invoice.periodStart` | `string \| null` | Start of the billing period, when set. | | `data.invoice.periodEnd` | `string \| null` | End of the billing period, when set. | | `data.invoice.paidAt` | `string \| null` | When the invoice was fully paid. Null until then. | | `data.invoice.expiresAt` | `string \| null` | When the invoice expires. | | `data.invoice.createdAt` | `string` | When the invoice was created (ISO 8601). | | `data.invoice.updatedAt` | `string` | When the invoice was last updated (ISO 8601). | | `data.payments` | `array \| null` | Payments made toward the invoice. Null when there are none. | | `data.payments[].sessionId` | `string` | Payment session the payment came through. | | `data.payments[].sessionReference` | `string` | Reference of that payment session. | | `data.payments[].status` | `string` | Payment status, such as `confirmed`. | | `data.payments[].asset` | `string` | Crypto asset paid. | | `data.payments[].chain` | `string` | Blockchain network. | | `data.payments[].amount` | `string` | Crypto amount paid. | | `data.payments[].txHash` | `string` | Transaction hash on the blockchain. | | `data.payments[].createdAt` | `string` | When the payment was detected. | | `data.payments[].confirmedAt` | `string \| null` | When the payment was confirmed. | ### Events * `invoice.updated` * `invoice.paid` * `invoice.expired` ### `invoice.updated` Sent when an invoice receives a payment or its status changes. `data.invoice.status` is `pending` or `partial`. Use this event to refresh totals and partial payment state. ```json { "event": "invoice.updated", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "partial", "state": "open", "isRefunded": false, "amount": "1000.00", "amountPaid": "500.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": null, "expiresAt": "2024-02-15T10:30:00.000Z", "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. `data.invoice.status` is `paid`. Use this event to fulfill the order. ```json { "event": "invoice.paid", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "paid", "state": "open", "isRefunded": false, "amount": "1000.00", "amountPaid": "1000.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": "2024-01-15T10:35:00.000Z", "expiresAt": "2024-02-15T10:30:00.000Z", "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. `data.invoice.status` is the payment status at expiry, `pending` or `partial`. Use this event to close unpaid invoices. ```json { "event": "invoice.expired", "data": { "invoice": { "id": "inv_123456789_abcdef", "reference": "INV-2024-001", "description": "Invoice for services rendered", "status": "pending", "state": "closed", "isRefunded": false, "amount": "1000.00", "amountPaid": "0.00", "currency": "NGN", "items": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Pro Plan subscription", "description": "January 2025 billing period", "unit": null, "quantity": "1", "unitPrice": "800.00", "lineTotal": "800.00" }, { "id": "123e4567-e89b-12d3-a456-426614174002", "name": "Additional seats", "description": "2 extra team members", "unit": "seats", "quantity": "2", "unitPrice": "100.00", "lineTotal": "200.00" } ], "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "customer@example.com", "phone": "+2348123456789", "firstName": "John", "lastName": "Doe", "telegramId": null, "metadata": { "userId": "usr_8f21c3" } }, "successUrl": "https://example.com/invoice/inv-2024-001", "cancelUrl": "https://example.com/invoice/inv-2024-001", "metadata": { "orderId": "ORDER-2024-001" }, "periodStart": null, "periodEnd": null, "paidAt": null, "expiresAt": "2024-01-15T10:30:00.000Z", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }, "payments": null } } ```