API reference
Invoices and payments
Billing periods, their invoices and the payments made against them. List and read invoices.
Use these endpoints to read invoices, charge them, and record payments made outside Abuna. A subscription bills one period at a time: each period has one invoice, and each attempt to pay it is a payment. To read all three for one subscription, retrieve the subscription. To send a customer to the pay page for an open invoice, use Create a payment session.
The billing period object
Creating a subscription returns its first billing period as period. Abuna creates the next one when a paid period ends, and issues its invoice.
Attributes
idstringUnique identifier for the billing period.subscription_idstringThe subscription the period belongs to.price_idstringThe price the period bills.pay_tokenstringThe token in the period's pay link.starts_attimestampWhen the period starts, in Unix seconds.ends_attimestampWhen the period ends, in Unix seconds.period_indexintegerThe period's place in the subscription, starting at0.grace_period_ends_attimestampThe pay-by date: the app's days to pay after the period starts, but never after it ends. If it passes unpaid, Abuna cancels the subscription.paid_attimestampnullableWhen the period was paid.paused_attimestampnullableReserved for paused periods. Always null.in_forcebooleanfalsefor an upgrade's period while it waits for payment, and for good if the upgrade lapses. Such a period doesn't count as one of the subscription's periods, and the next period reuses itsperiod_index.created_attimestampWhen the period was created, in Unix seconds.
{
"id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"price_id": "Zt6YbN3q",
"pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"starts_at": 1727600000,
"ends_at": 1730192000,
"period_index": 0,
"grace_period_ends_at": 1727686400,
"paid_at": null,
"paused_at": null,
"in_force": true,
"created_at": 1727600000
}The invoice object
An invoice keeps the amount, buyer and seller as they were when Abuna issued it. Later changes don't alter it.
Invoice numbers read like MYST-000124: the app's invoice_prefix, then the app's count of invoices, padded to 6 digits and longer past 999999. Each invoice the app issues takes the next count, so numbers never repeat and none are skipped. Live and Test mode count separately. A number never changes once issued, even if you change the prefix.
Attributes
idstringUnique identifier for the invoice.app_idstringThe app that issued the invoice.period_idstringThe billing period the invoice bills.subscription_idstringThe subscription the invoice belongs to.numberstringThe invoice number, likeMYST-000124. See invoice numbers.statusstringopenuntil paid, thenpaid.voidwhen the subscription was canceled before it was paid, or a plan change replaced it. A void invoice becomespaidif a payment the customer had already approved goes through after it was voided. See Payments that arrive late.kindstringamountintegerThe amount due, in the currency's smallest unit.creditintegerThe unused time of the previous period taken off the price.0unlesskindisplan_change.currencystringThe price's currency:XAF,XOForUSD.item_labelstringThe price's name.buyer_namestringnullableThe customer's name.buyer_emailstringnullableThe customer's email address.seller_namestringThe app's name.period_starttimestampWhen the billed period starts.period_endtimestampWhen the billed period ends.due_attimestampThe pay-by date.created_attimestampWhen the invoice was issued, in Unix seconds.paid_attimestampnullableWhen the invoice was paid.voided_attimestampnullableWhen the invoice was voided. Null again once a late payment makes it paid.discountintegerWhat the invoice's coupon took off it, in the currency's smallest unit.0without one.amountis already after it.coupon_idstringnullableThe coupon that took the discount off. Null without one.promotion_code_idstringnullableThe promotion code that brought the coupon. Null when you applied the coupon directly, without a code.
{
"id": "V2nC8xEi",
"app_id": "8ddhXCDW",
"period_id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"number": "MYST-000124",
"status": "open",
"kind": "period",
"amount": 5000,
"credit": 0,
"currency": "XAF",
"item_label": "Monthly",
"buyer_name": "Jane Doe",
"buyer_email": "jane@example.com",
"seller_name": "My store",
"period_start": 1727600000,
"period_end": 1730192000,
"due_at": 1727686400,
"created_at": 1727600000,
"paid_at": null,
"voided_at": null,
"discount": 0,
"coupon_id": null,
"promotion_code_id": null
}The payment object
Customers pay by mobile money in FCFA. When the invoice is in another currency, the payment saves the conversion: an invoice for $10.00 paid on a Cameroon number is charged FCFA 6,039 at the day's rate plus 2%. See Paying in FCFA.
Attributes
idstringUnique identifier for the payment.app_idstringThe app the payment belongs to.period_idstringThe billing period the payment is for.driverstringThe payment provider, likepawapay.abunafor a payment through Abuna payments,sandboxfor a simulated Test payment, andmanualfor a payment you marked paid.providerstringThe network the provider charged, likeMTN_MOMO_CMR.manualfor a payment you marked paid.provider_referencestringnullableThe provider's own ID for the charge.amountintegerThe amount charged, in the currency's smallest unit.currencystringThe currency charged. For mobile money, the network's:XAForXOF. For a payment you marked paid, the invoice's currency, with no conversion.original_amountintegernullableThe invoice's amount, in its currency's smallest unit. Null on payments made before 13 November 2026.original_currencystringnullableThe invoice's currency:XAF,XOForUSD. Null on payments made before 13 November 2026.exchange_ratenumbernullableThe francs charged per unit oforiginal_currency(per dollar for USD), 2% included, like603.8094.1between XOF and XAF. Null when the invoice was already in the charged currency.exchange_margin_bpsintegernullableThe margin included inexchange_rate, in hundredths of a percent:200is 2%.0between XOF and XAF. Null when the invoice was already in the charged currency.exchange_rate_attimestampnullableWhen the rate used was published, in Unix seconds. Between XOF and XAF, when the payment started. Null when the invoice was already in the charged currency.statusstringpending,succeededorfailed. Afailedpayment whose outcome the provider hadn't confirmed can still becomesucceeded, usually within 7 days of when it started; seeinvoice.payment_failed.messagestringnullableA short note about the payment for people to read, such as why it failed. Don't parse it, since its wording can change. To know why a payment failed, branch onfailureininvoice.payment_failed. Null when there's no note.created_attimestampWhen the payment started, in Unix seconds.feeintegernullableThe provider's fee, in the currency's smallest unit. In Live mode it is null until the provider reports it. In Test mode it is an estimate. For a payment through Abuna payments, it is Abuna's 3.5% fee instead, rounded down to the whole franc, set once the payment succeeds.netintegernullableFor a payment through Abuna payments, what you receive:amountminusfee, set once the payment succeeds. Null for every other payment.session_idstringnullableThe session used to make this payment, or null for a payment made another way.notestringnullableFor a payment you marked paid, the note you gave about how the customer paid. Customers never see it. Null otherwise.marked_by_user_idstringnullableFor a payment marked paid from the dashboard, the ID of the team member who marked it. Null otherwise.marked_by_api_key_idstringnullableFor a payment marked paid with a secret key, the ID of that key. Null otherwise.method_labelstringThe network's name, in words.Paid outside Abunafor a payment you marked paid.
{
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": 100,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
}{
"amount": 6039,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "sandbox",
"exchange_margin_bps": 200,
"exchange_rate": 603.8094,
"exchange_rate_at": 1791100800,
"fee": 120,
"id": "tGfwt5dd",
"marked_by_api_key_id": null,
"marked_by_user_id": null,
"message": null,
"method_label": "Successful payment (test)",
"net": null,
"note": null,
"original_amount": 1000,
"original_currency": "USD",
"period_id": "0kYPFwxJ",
"provider": "test",
"provider_reference": "test_ff6aaf0182bd3f1148bd",
"session_id": null,
"status": "succeeded"
}The invoice summary object
The invoice endpoints return invoices in this shape. It adds the customer and whether the invoice is unpaid past its pay-by date, and leaves out app_id, period_id and seller_name.
Attributes
idstringUnique identifier for the invoice.numberstringThe invoice number, likeMYST-000124. See invoice numbers.statusstringopenuntil paid, thenpaid.voidwhen the subscription was canceled before it was paid, or a plan change replaced it. A void invoice becomespaidif a payment the customer had already approved goes through after it was voided. See Payments that arrive late.overduebooleantruewhen the invoice isopenand itsdue_athas passed. It is worked out each time you ask, and is not a status.kindstringamountintegerThe amount due, in the currency's smallest unit.creditintegerThe unused time taken off the price, as on the invoice object.currencystringThe price's currency:XAF,XOForUSD.item_labelstringThe price's name.buyer_namestringnullableThe customer's name.buyer_emailstringnullableThe customer's email address.subscription_idstringThe subscription the invoice belongs to.customer_idstringThe subscription's customer.period_starttimestampWhen the billed period starts.period_endtimestampWhen the billed period ends.due_attimestampThe billing period's pay-by date (grace_period_ends_at), as it stands now. It can differ from thedue_aton the invoice object, which is set when the invoice is issued.created_attimestampWhen the invoice was issued, in Unix seconds.paid_attimestampnullableWhen the invoice was paid.voided_attimestampnullableWhen the invoice was voided. Null again once a late payment makes it paid.discountintegerWhat the invoice's coupon took off it, as on the invoice object.coupon_idstringnullableThe coupon that took the discount off, as on the invoice object.promotion_code_idstringnullableThe promotion code that brought the coupon, as on the invoice object.
{
"id": "V2nC8xEi",
"number": "MYST-000124",
"status": "open",
"overdue": false,
"kind": "period",
"amount": 5000,
"credit": 0,
"currency": "XAF",
"item_label": "Monthly",
"buyer_name": "Jane Doe",
"buyer_email": "jane@example.com",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"period_start": 1727600000,
"period_end": 1730192000,
"due_at": 1727686400,
"created_at": 1727600000,
"paid_at": null,
"voided_at": null,
"discount": 0,
"coupon_id": null,
"promotion_code_id": null
}List invoices
GET/v1/apps/{appID}/invoices
Lists the app's invoices, newest first, one page at a time. Test mode and Live mode have separate invoices, so a list shows only the mode of the app you ask about. All parameters are optional, and a blank one is ignored.
Parameters
statusstringopen,paid,voidoroverdue.openincludes invoices past their pay-by date.overduereturns only the open invoices whose pay-by date has passed.searchstringPart of the invoice number, buyer name or buyer email. Ignores case.fromtimestampOnly invoices issued at or after this time, in Unix seconds.totimestampOnly invoices issued before this time, in Unix seconds.customer_idstringOnly invoices for this customer.limitintegerHow many invoices to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Response attributes
itemsarrayThe page's invoices. Empty when nothing matches.next_cursorstringnullablePass it as cursor to get the next page. It is null on the last page. Treat it as opaque.
Returns 200. A value that isn't allowed returns 422 with code invalid and the parameter's name in errors.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "V2nC8xEi",
"number": "MYST-000124",
"status": "open",
"overdue": false,
"kind": "period",
"amount": 5000,
"credit": 0,
"currency": "XAF",
"item_label": "Monthly",
"buyer_name": "Jane Doe",
"buyer_email": "jane@example.com",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"period_start": 1727600000,
"period_end": 1730192000,
"due_at": 1727686400,
"created_at": 1727600000,
"paid_at": null,
"voided_at": null,
"discount": 0,
"coupon_id": null,
"promotion_code_id": null
}
],
"next_cursor": "MTcyNzYwMDAwMDAwMDAwMC4wMUo5WlE3VjFXMlgzWTRaNUE2QjdDOEQ5RQ"
}Retrieve an invoice
GET/v1/apps/{appID}/invoices/{id}
Retrieves an invoice with its links and its history, from when it was issued to when it was paid or voided.
Response attributes
invoiceobjectpay_urlstringnullableThe pay link for the billing period. It is null once the invoice is paid or void, or when the subscription is canceled.invoice_urlstringA link to the customer's invoice page, which also shows paid and void invoices. It expires after 7 days.timelinearrayWhat happened to the invoice, oldest first. Events in the same second come in the order below.Show child attributesHide child attributes
typestringissued: Abuna issued the invoice.reminder: Abuna scheduled a reminder.notice: a message to the customer about the invoice.payment: an attempt to pay, whether it succeeded, failed or is still pending.paid: the invoice was paid.voided: the invoice was voided.
attimestampWhen it happened, in Unix seconds. For a message, when it was sent, or created if it isn't sent yet.noticeobjectpaymentobjectreminderobjectOn areminderevent: an object withkind, one ofrenewal_upcoming,payment_overdueorpayment_final_notice.
Returns 200. If the app has no invoice with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi \
-H "Authorization: Bearer sk_test_..."{
"invoice": {
"id": "V2nC8xEi",
"number": "MYST-000124",
"status": "open",
"overdue": false,
"kind": "period",
"amount": 5000,
"credit": 0,
"currency": "XAF",
"item_label": "Monthly",
"buyer_name": "Jane Doe",
"buyer_email": "jane@example.com",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"period_start": 1727600000,
"period_end": 1730192000,
"due_at": 1727686400,
"created_at": 1727600000,
"paid_at": null,
"voided_at": null,
"discount": 0,
"coupon_id": null,
"promotion_code_id": null
},
"pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d",
"timeline": [
{ "type": "issued", "at": 1727600000 },
{
"type": "notice",
"at": 1727600002,
"notice": {
"id": "e7JpT4cN",
"customer_id": "Cu5tM8rA",
"subscription_id": "x9QbL2sK",
"kind": "subscription_started",
"channel": "email",
"recipient": "jane@example.com",
"subject": "Pay FCFA 5,000 to start your Pro · Monthly plan with My store",
"status": "sent",
"attempts": 1,
"last_error": null,
"next_attempt_at": 1727600000,
"created_at": 1727600000,
"sent_at": 1727600002
}
},
{
"type": "payment",
"at": 1727600090,
"payment": {
"id": "m7Yw4NcJ",
"app_id": "8ddhXCDW",
"period_id": "T6yVr3Dp",
"driver": "pawapay",
"provider": "MTN_MOMO_CMR",
"provider_reference": "9f3b7d1a-5c2e-8f4b-6d0a-3e7c1b5a9d2f",
"amount": 5000,
"currency": "XAF",
"original_amount": 5000,
"original_currency": "XAF",
"exchange_rate": null,
"exchange_margin_bps": null,
"exchange_rate_at": null,
"status": "failed",
"message": "INSUFFICIENT_BALANCE: The payer's balance is too low",
"created_at": 1727600090,
"fee": 100,
"net": null,
"session_id": null,
"note": null,
"marked_by_user_id": null,
"marked_by_api_key_id": null,
"method_label": "MTN Mobile Money Cameroon"
}
},
{ "type": "reminder", "at": 1727686400, "reminder": { "kind": "payment_overdue" } }
]
}Charge an invoice
POST/v1/apps/{appID}/invoices/{id}/charge
Accepts an Idempotency-Key header.
Charges the customer's saved phone number for an open invoice. The customer approves the payment on their phone. The charge goes to the number's network, such as Orange Money for a Cameroon number starting with 69. When the prefix doesn't show the network, it goes to the network the customer last paid with. With the Abuna simulator in Test, the charge always succeeds. To have the customer pay on the pay page instead, use Create a payment session.
Response attributes
statusstringsucceeded, orpendingwhile the customer approves the charge on their phone.paidbooleantruewhenstatusissucceeded.periodobjectThe invoice's billing period.
Returns 200. A charge refused immediately returns 402 with the reason as its code, like insufficient_funds or payment_declined. These also fail:
403plan_limit: the customer's first payment would pass the Live subscriber limit of your team's plan.404not_found: the app has no invoice with that ID.409already_paid: the invoice is paid.409invoice_not_open: the invoice is void, because the subscription was canceled.409payment_in_progress: another payment for the invoice is still pending.422not_accepting_payments: a Live app can't take payments yet.422payment_unavailable: your provider has no network that can charge the customer's number.422phone_required, on the fieldphone_number: the customer has no phone number yet. Set one with Update a customer, or send them a payment session, which asks for it.503payment_paused: no new payment was started. An earlier payment on the invoice may still be in progress. Try again in about a minute.503exchange_rate_unavailable: the invoice is in USD and no recent exchange rate is available. Nothing was charged. Try again later.
A pending charge can still fail, for example when the customer declines it on their phone or their balance is too low. You then get invoice.payment_failed. Its failure field gives the reason, with the same codes as a 402, like insufficient_funds. A failed payment whose outcome the provider hadn't confirmed can still be paid later, usually within 7 days of when it started, so wait for invoice.paid before you refund or cancel anything.
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge \
-H "Authorization: Bearer sk_test_..."{
"status": "succeeded",
"paid": true,
"period": {
"id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"price_id": "Zt6YbN3q",
"pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"starts_at": 1727600000,
"ends_at": 1730192000,
"period_index": 0,
"grace_period_ends_at": 1727686400,
"paid_at": 1727600100,
"paused_at": null,
"in_force": true,
"created_at": 1727600000
}
}Mark an invoice paid
POST/v1/apps/{appID}/invoices/{id}/mark-paid
Accepts an Idempotency-Key header.
Records that the customer paid an open invoice outside Abuna, such as in cash, by bank transfer or straight to your own mobile money number. Abuna charges nothing. The invoice is then paid like any other: the subscription starts, renews or stops being unpaid (past_due), you get invoice.paid and the subscription events that follow, and the customer gets a receipt saying you recorded their payment. A renewal marked paid before it starts keeps its dates.
Parameters
notestringrequiredHow the customer paid, for your own records, like a receipt or transfer reference. 1 to 500 characters, with spaces trimmed from both ends. Customers never see it.
Response attributes
statusstringAlwayssucceeded.paidbooleanAlwaystrue.periodobjectThe invoice's billing period, now paid.paymentobjectThe recorded payment: the invoice's amount and currency with no conversion,driverandprovidermanual, no fee, and your note.
Returns 200. These fail:
403plan_limit: the customer's first payment would pass the Live subscriber limit of your team's plan.404not_found: the app has no invoice with that ID.409already_paid: the invoice is paid.409invoice_not_open: the invoice is void, for example because the subscription was canceled.409payment_in_progress: a mobile money payment for the invoice is waiting for the customer's approval. Try again once it succeeds or fails, with a newIdempotency-Keyif you sent one.422invalid: the note is missing or blank (required) or longer than 500 characters (too_long), inerrors.
curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: cash-V2nC8xEi" \
-d '{
"note": "Paid cash at the shop, receipt 0042"
}'{
"status": "succeeded",
"paid": true,
"period": {
"id": "T6yVr3Dp",
"subscription_id": "x9QbL2sK",
"price_id": "Zt6YbN3q",
"pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d",
"starts_at": 1727600000,
"ends_at": 1730192000,
"period_index": 0,
"grace_period_ends_at": 1727686400,
"paid_at": 1727600100,
"paused_at": null,
"in_force": true,
"created_at": 1727600000
},
"payment": {
"amount": 5000,
"app_id": "qhf83tDc",
"created_at": 1794780106,
"currency": "XAF",
"driver": "manual",
"exchange_margin_bps": null,
"exchange_rate": null,
"exchange_rate_at": null,
"fee": null,
"id": "tGfwt5dd",
"marked_by_api_key_id": "01J9ZQ5K2M3N4P5Q6R7S8T9V0W",
"marked_by_user_id": null,
"message": null,
"method_label": "Paid outside Abuna",
"net": null,
"note": "Paid cash at the shop, receipt 0042",
"original_amount": 5000,
"original_currency": "XAF",
"period_id": "0kYPFwxJ",
"provider": "manual",
"provider_reference": null,
"session_id": null,
"status": "succeeded"
}
}Next steps
- SubscriptionsStart, list, read, update, cancel, keep and change the plan of a customer's subscription.
- Customer messagesThe emails, Telegram and WhatsApp messages Abuna sent your customers.
- Lists and filtersWhat list endpoints return, how to page through and filter them, and how to treat IDs.
- EventsThe record of everything that happened in an app, and every event type.