Billing & Payments API
Invoice management, payment initiation, transaction monitoring, callback handling, and development test routes. This page documents routes exposed from the billing blueprint. Base URL prefix: <API_BASE_URL>.
Authentication and roles
Admin invoice, COD collection, and transaction monitoring endpoints require Authorization: Bearer <access_token> and admin role. Checkout/payment and callback endpoints are public by design. Test endpoints are enabled only in debug/testing or when test routes are explicitly enabled in config.
Invoice management
List all invoices.
List pending invoices.
List overdue invoices.
List paid invoices.
Get invoice details with items and payment summary.
Create invoice manually. Body supports customer fields, optional user_id, currency/tax IDs, destination country, payment terms, notes, and items.
Update editable invoice fields and optional currency/tax selection.
Add item to invoice. Body: product_id, optional name/sku overrides, quantity, unit_price, tax_rate, variant_info.
Remove invoice item from a specific invoice.
Cancel invoice when allowed by status.
COD and transactions
Mark COD transaction as collected. Body supports collector, delivery agent ID, and notes.
Verify COD payment using verification code.
List all payment transactions.
Get transaction details including gateway-specific data.
List all transactions for an invoice.
Checkout and invoice payment
List enabled payment methods for checkout.
Get invoice by invoice number.
Get invoice payment payload with available methods.
Initiate M-Pesa STK push. Body: invoice_id, phone_number, amount.
Query M-Pesa transaction status by checkout request ID.
Initiate Pesapal payment and return redirect URL. Body: invoice_id, amount, currency.
Query Pesapal transaction status.
Pesapal return URL target after customer payment flow.
Create Cash on Delivery transaction. Body: invoice_id.
Get COD instructions and verification details.
Get unified payment status by transaction reference.
Gateway callback routes
M-Pesa STK callback handler.
Optional M-Pesa validation callback endpoint.
Optional M-Pesa confirmation callback endpoint.
Pesapal IPN callback endpoint supporting POST and GET delivery modes.
Test routes
These endpoints are development-only and return 404 when test routes are disabled.
Create sample invoice with test items.
Seed M-Pesa, Pesapal, and COD methods for local/dev testing.
Simulate M-Pesa callback payload.
Simulate Pesapal IPN payload.
Get full test invoice details with payments.
Get test transaction details including gateway data.
Common responses
Validation and state errors return 400. Missing resources return 404. Missing/invalid auth returns 401. Forbidden admin access returns 403. Gateway integration failures return 500 with a normalized {"error": "..."} response body.