Skip to content
ABUNA
DocsInvoices and payments

API reference

Invoices and payments

Billing periods, their invoices and the payments made against them. List and read invoices.

View as Markdown

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

  • idstring

    Unique identifier for the billing period.
  • subscription_idstring

    The subscription the period belongs to.
  • price_idstring

    The price the period bills.
  • pay_tokenstring

    The token in the period's pay link.
  • starts_attimestamp

    When the period starts, in Unix seconds.
  • ends_attimestamp

    When the period ends, in Unix seconds.
  • period_indexinteger

    The period's place in the subscription, starting at 0.
  • grace_period_ends_attimestamp

    The 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_attimestampnullable

    When the period was paid.
  • paused_attimestampnullable

    Reserved for paused periods. Always null.
  • in_forceboolean

    false for 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 its period_index.
  • created_attimestamp

    When the period was created, in Unix seconds.
The billing period object
{
  "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

  • idstring

    Unique identifier for the invoice.
  • app_idstring

    The app that issued the invoice.
  • period_idstring

    The billing period the invoice bills.
  • subscription_idstring

    The subscription the invoice belongs to.
  • numberstring

    The invoice number, like MYST-000124. See invoice numbers.
  • statusstring

    open until paid, then paid. void when the subscription was canceled before it was paid, or a plan change replaced it. A void invoice becomes paid if a payment the customer had already approved goes through after it was voided. See Payments that arrive late.
  • kindstring

    period for a billing period, or plan_change for the first period of an upgrade. See Upgrades.
  • amountinteger

    The amount due, in the currency's smallest unit.
  • creditinteger

    The unused time of the previous period taken off the price. 0 unless kind is plan_change.
  • currencystring

    The price's currency: XAF, XOF or USD.
  • item_labelstring

    The price's name.
  • buyer_namestringnullable

    The customer's name.
  • buyer_emailstringnullable

    The customer's email address.
  • seller_namestring

    The app's name.
  • period_starttimestamp

    When the billed period starts.
  • period_endtimestamp

    When the billed period ends.
  • due_attimestamp

    The pay-by date.
  • created_attimestamp

    When the invoice was issued, in Unix seconds.
  • paid_attimestampnullable

    When the invoice was paid.
  • voided_attimestampnullable

    When the invoice was voided. Null again once a late payment makes it paid.
  • discountinteger

    What the invoice's coupon took off it, in the currency's smallest unit. 0 without one. amount is already after it.
  • coupon_idstringnullable

    The coupon that took the discount off. Null without one.
  • promotion_code_idstringnullable

    The promotion code that brought the coupon. Null when you applied the coupon directly, without a code.
The invoice object
{
  "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

  • idstring

    Unique identifier for the payment.
  • app_idstring

    The app the payment belongs to.
  • period_idstring

    The billing period the payment is for.
  • driverstring

    The payment provider, like pawapay. abuna for a payment through Abuna payments, sandbox for a simulated Test payment, and manual for a payment you marked paid.
  • providerstring

    The network the provider charged, like MTN_MOMO_CMR. manual for a payment you marked paid.
  • provider_referencestringnullable

    The provider's own ID for the charge.
  • amountinteger

    The amount charged, in the currency's smallest unit.
  • currencystring

    The currency charged. For mobile money, the network's: XAF or XOF. For a payment you marked paid, the invoice's currency, with no conversion.
  • original_amountintegernullable

    The invoice's amount, in its currency's smallest unit. Null on payments made before 13 November 2026.
  • original_currencystringnullable

    The invoice's currency: XAF, XOF or USD. Null on payments made before 13 November 2026.
  • exchange_ratenumbernullable

    The francs charged per unit of original_currency (per dollar for USD), 2% included, like 603.8094. 1 between XOF and XAF. Null when the invoice was already in the charged currency.
  • exchange_margin_bpsintegernullable

    The margin included in exchange_rate, in hundredths of a percent: 200 is 2%. 0 between XOF and XAF. Null when the invoice was already in the charged currency.
  • exchange_rate_attimestampnullable

    When 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.
  • statusstring

    pending, succeeded or failed. A failed payment whose outcome the provider hadn't confirmed can still become succeeded, usually within 7 days of when it started; see invoice.payment_failed.
  • messagestringnullable

    A 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 on failure in invoice.payment_failed. Null when there's no note.
  • created_attimestamp

    When the payment started, in Unix seconds.
  • feeintegernullable

    The 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.
  • netintegernullable

    For a payment through Abuna payments, what you receive: amount minus fee, set once the payment succeeds. Null for every other payment.
  • session_idstringnullable

    The session used to make this payment, or null for a payment made another way.
  • notestringnullable

    For a payment you marked paid, the note you gave about how the customer paid. Customers never see it. Null otherwise.
  • marked_by_user_idstringnullable

    For a payment marked paid from the dashboard, the ID of the team member who marked it. Null otherwise.
  • marked_by_api_key_idstringnullable

    For a payment marked paid with a secret key, the ID of that key. Null otherwise.
  • method_labelstring

    The network's name, in words. Paid outside Abuna for a payment you marked paid.
The payment object
{
  "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"
}
A $10.00 invoice paid in XAF
{
  "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

  • idstring

    Unique identifier for the invoice.
  • numberstring

    The invoice number, like MYST-000124. See invoice numbers.
  • statusstring

    open until paid, then paid. void when the subscription was canceled before it was paid, or a plan change replaced it. A void invoice becomes paid if a payment the customer had already approved goes through after it was voided. See Payments that arrive late.
  • overdueboolean

    true when the invoice is open and its due_at has passed. It is worked out each time you ask, and is not a status.
  • kindstring

    period or plan_change, as on the invoice object.
  • amountinteger

    The amount due, in the currency's smallest unit.
  • creditinteger

    The unused time taken off the price, as on the invoice object.
  • currencystring

    The price's currency: XAF, XOF or USD.
  • item_labelstring

    The price's name.
  • buyer_namestringnullable

    The customer's name.
  • buyer_emailstringnullable

    The customer's email address.
  • subscription_idstring

    The subscription the invoice belongs to.
  • customer_idstring

    The subscription's customer.
  • period_starttimestamp

    When the billed period starts.
  • period_endtimestamp

    When the billed period ends.
  • due_attimestamp

    The billing period's pay-by date (grace_period_ends_at), as it stands now. It can differ from the due_at on the invoice object, which is set when the invoice is issued.
  • created_attimestamp

    When the invoice was issued, in Unix seconds.
  • paid_attimestampnullable

    When the invoice was paid.
  • voided_attimestampnullable

    When the invoice was voided. Null again once a late payment makes it paid.
  • discountinteger

    What the invoice's coupon took off it, as on the invoice object.
  • coupon_idstringnullable

    The coupon that took the discount off, as on the invoice object.
  • promotion_code_idstringnullable

    The promotion code that brought the coupon, as on the invoice object.
The invoice summary 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

  • statusstring

    open, paid, void or overdue. open includes invoices past their pay-by date. overdue returns only the open invoices whose pay-by date has passed.
  • searchstring

    Part of the invoice number, buyer name or buyer email. Ignores case.
  • fromtimestamp

    Only invoices issued at or after this time, in Unix seconds.
  • totimestamp

    Only invoices issued before this time, in Unix seconds.
  • customer_idstring

    Only invoices for this customer.
  • limitinteger

    How many invoices to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from the previous page. Send the same filters with it.

Response attributes

  • itemsarray

    The page's invoices. Empty when nothing matches.
  • next_cursorstringnullable

    Pass 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.

GET /v1/apps/{appID}/invoices
curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • invoiceobject

  • pay_urlstringnullable

    The pay link for the billing period. It is null once the invoice is paid or void, or when the subscription is canceled.
  • invoice_urlstring

    A link to the customer's invoice page, which also shows paid and void invoices. It expires after 7 days.
  • timelinearray

    What happened to the invoice, oldest first. Events in the same second come in the order below.
    Show child attributesHide child attributes
    • typestring

      • issued: 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.
    • attimestamp

      When it happened, in Unix seconds. For a message, when it was sent, or created if it isn't sent yet.
    • noticeobject

      On a notice event: the notice object. Its recipient is empty for Telegram.
    • paymentobject

      On a payment event: the payment object. Its status says how the attempt ended.
    • reminderobject

      On a reminder event: an object with kind, one of renewal_upcoming, payment_overdue or payment_final_notice.

Returns 200. If the app has no invoice with that ID, returns 404 with code not_found.

GET /v1/apps/{appID}/invoices/{id}
curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • statusstring

    succeeded, or pending while the customer approves the charge on their phone.
  • paidboolean

    true when status is succeeded.
  • periodobject

    The 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:

  • 403 plan_limit: the customer's first payment would pass the Live subscriber limit of your team's plan.
  • 404 not_found: the app has no invoice with that ID.
  • 409 already_paid: the invoice is paid.
  • 409 invoice_not_open: the invoice is void, because the subscription was canceled.
  • 409 payment_in_progress: another payment for the invoice is still pending.
  • 422 not_accepting_payments: a Live app can't take payments yet.
  • 422 payment_unavailable: your provider has no network that can charge the customer's number.
  • 422 phone_required, on the field phone_number: the customer has no phone number yet. Set one with Update a customer, or send them a payment session, which asks for it.
  • 503 payment_paused: no new payment was started. An earlier payment on the invoice may still be in progress. Try again in about a minute.
  • 503 exchange_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.

POST /v1/apps/{appID}/invoices/{id}/charge
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • notestringrequired

    How 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

  • statusstring

    Always succeeded.
  • paidboolean

    Always true.
  • periodobject

    The invoice's billing period, now paid.
  • paymentobject

    The recorded payment: the invoice's amount and currency with no conversion, driver and provider manual, no fee, and your note.

Returns 200. These fail:

  • 403 plan_limit: the customer's first payment would pass the Live subscriber limit of your team's plan.
  • 404 not_found: the app has no invoice with that ID.
  • 409 already_paid: the invoice is paid.
  • 409 invoice_not_open: the invoice is void, for example because the subscription was canceled.
  • 409 payment_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 new Idempotency-Key if you sent one.
  • 422 invalid: the note is missing or blank (required) or longer than 500 characters (too_long), in errors.
POST /v1/apps/{appID}/invoices/{id}/mark-paid
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"
  }'
Response
{
  "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