Invoices let you bill customers with itemized line items, apply taxes and discounts, and collect payment through multiple channels. Hyparrow generates a unique invoice number for every invoice and keeps totals consistent across updates.
Create an invoice
Create the invoice
Send a POST request with your company details, customer details, and at least one line item. You can include line items inline at creation time or add them individually afterward. Internal title for the invoice (e.g. “Q1 Retainer”).
ISO 4217 currency code, exactly 3 characters (e.g. NGN, USD).
Your company name as it will appear on the invoice.
Your company billing email address.
ISO 8601 date-time. Defaults to now if omitted.
ISO 8601 date-time for when payment is due.
Full name of the customer being billed.
Customer’s email address. Required to send the invoice by email.
Street address of the customer.
Invoice-level tax mode: none, percentage, or fixed. When set to anything other than none, this overrides any line-item tax settings.
Tax value. For percentage, supply a percent (e.g. 7.5 for 7.5%). For fixed, supply a flat currency amount applied per line item.
Invoice-level discount mode: none, percentage, or fixed. Overrides line-item discounts when set.
Discount value, interpreted according to discountType.
Flat shipping fee added to the invoice total.
Free-text notes printed at the bottom of the invoice.
Arbitrary key-value pairs stored on the invoice. Not shown to customers.
URL that Hyparrow POSTs to when a checkout-link payment changes status (completed, pending, or failed).
Array of line items. At least one is required.
curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/ \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret" \ --header "Content-Type: application/json" \ --data '{ "title": "Web Development Services", "currency": "NGN", "companyName": "Acme Corp", "email": "billing@acme.com", "customerName": "Jane Doe", "customerEmail": "jane@example.com", "billingAddress": "12 Marina Street", "city": "Lagos", "state": "Lagos", "country": "Nigeria", "taxType": "percentage", "taxRate": 7.5, "discountType": "none", "shippingFee": 0, "notes": "Payment due within 14 days.", "lineItems": [ { "description": "Frontend development", "quantity": 10, "unitPrice": 50000 }, { "description": "Hosting setup", "quantity": 1, "unitPrice": 25000 } ] }'
{ "success" : true , "message" : "Invoice created successfully" , "data" : { "id" : "a1b2c3d4-e5f6-..." , "invoiceNumber" : "invoice-hpw-000000001" , "status" : "draft" , "currency" : "NGN" , "subTotal" : 525000.00 , "taxTotal" : 39375.00 , "discountTotal" : 0.00 , "totalAmount" : 564375.00 , "lineItems" : [] } }
Add line items (optional)
Add line items after creation with POST /api/v1/invoices/:invoiceId/line-items. Description of the product or service.
Number of units. Must be greater than 0.
Price per unit. Must be greater than 0.
ID of an existing product. When provided, description and unitPrice are auto-populated from the product. You may still override unitPrice explicitly.
Line-item tax mode: none, percentage, or fixed. Only used when the invoice-level taxType is none.
Line-item discount mode: none, percentage, or fixed. Only used when the invoice-level discountType is none.
Line-item discount value.
curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-.../line-items \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret" \ --header "Content-Type: application/json" \ --data '{ "description": "Domain registration", "quantity": 1, "unitPrice": 15000 }'
Generate a virtual account
Create a short-lived virtual account that your customer pays into. Hyparrow automatically marks the invoice as paid when the exact amount clears. VA lifetime in minutes. Must be exactly 10, 15, or 30.
curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-.../generate-va \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret" \ --header "Content-Type: application/json" \ --data '{ "expiryMinutes": 30 }'
{ "success" : true , "message" : "Virtual account generated — pay the exact amount before it expires" , "data" : { "accountNumber" : "0123456789" , "accountName" : "Hyparrow / Jane Doe" , "bankName" : "Wema Bank" , "bankCode" : "035" , "expiresAt" : "2025-06-01T12:30:00Z" } }
The customer must transfer the exact invoice total before the VA expires. Partial or over-payments are not automatically applied.
Check invoice status
Retrieve the invoice to confirm payment. curl --request GET \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-... \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret"
The status field will be one of: Value Meaning draftCreated, not yet sent pendingSent to customer, awaiting payment paidPayment confirmed overdueDue date passed without payment canceledInvoice voided
Download PDF Returns a PDF binary with Content-Type: application/pdf.
curl --request GET \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-.../download \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret" \ --output invoice.pdf
Send by email Emails the invoice PDF to the customer address on record. The email includes a checkout link.
curl --request POST \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-.../send-email \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret"
{ "success" : true , "message" : "Invoice emailed to jane@example.com" }
The invoice must have a customerEmail set. Requests without one return a 400 error.
Public checkout Give customers a hosted payment page — no authentication required on their side.
GET https://api.hyparrow.com/api/v1/checkout/:invoiceId
The checkout page accepts payment via virtual account bank transfer, card, USSD, OPay, and crypto. When payment status changes, Hyparrow POSTs to the checkoutCallbackUrl you set on the invoice (if any).
List invoices curl --request GET \ --url "https://api.hyparrow.com/api/v1/invoices/?page=1&limit=20&status=pending" \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret"
Query parameter Type Default Description pagenumber 1Page number limitnumber 20Results per page statusstring — Filter by invoice status
Receipt Once an invoice is paid, retrieve or download the branded receipt.
Get receipt JSON
Download receipt PDF
curl --request GET \ --url https://api.hyparrow.com/api/v1/invoices/a1b2c3d4-.../receipt \ --header "x-api-key: your_api_key" \ --header "x-api-secret: your_api_secret"
