Invoices & Billing

Invoices represent bills itemizing products and services. Invoices are compiled automatically for recurring subscriptions at the start of each billing period, or they can be created manually via the Xtopay Dashboard to bill clients for custom work.

---

Invoice Statuses

An invoice progresses through several statuses during its billing lifecycle:

---

Invoice Structure & Line Items

An invoice consists of core financial parameters and a list of detailed line items:

Core Financials

All financial values are stored as integers in minor units (e.g. 5000 is 50.00 GHS/USD):

• Subtotal: Sum of all invoice line items before discounts or taxes are applied.
• Tax: Total tax amount added.
• Discount: Total discount amount deducted.
• Total: Final amount computed as Subtotal + Tax - Discount.
• Amount Due: The remaining unpaid balance on the invoice.
• Amount Paid: The total cumulative payments successfully charged against this invoice.

Invoice Line Items

Each line item includes:

• Description: Name or note of the service/item.
• Quantity: Number of units billed.
• Unit Amount: Price per single unit in minor units.
• Amount: Aggregated value calculated as Quantity * Unit Amount.

---

Collecting Payments

When an invoice status transitions to OPEN, Xtopay assigns a secure payment link where customers can complete checkout using Cards, Mobile Money, or Bank Transfers.

Once the payment succeeds:

1. The invoice Amount Paid increases, and Amount Due transitions to 0.
2. The invoice status updates to PAID.
3. If this invoice is associated with a subscription, the subscription is updated to ACTIVE (or stays active).
4. An invoice.paid webhook event is dispatched to your configured endpoint.

To learn how to process webhook events for paid invoices, check out the Webhooks guide.