# Invoices and payments > Billing periods, their invoices and the payments made against them. List and read invoices. Source: https://abuna.app/docs/api/invoices-and-payments 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](https://abuna.app/docs/api/subscriptions.md#retrieve). To send a customer to the pay page for an open invoice, use [Create a payment session](https://abuna.app/docs/api/sessions.md#create-payment). ## 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** - `id` (string): Unique identifier for the billing period. - `subscription_id` (string): The subscription the period belongs to. - `price_id` (string): The price the period bills. - `pay_token` (string): The token in the period's pay link. - `starts_at` (timestamp): When the period starts, in Unix seconds. - `ends_at` (timestamp): When the period ends, in Unix seconds. - `period_index` (integer): The period's place in the subscription, starting at `0`. - `grace_period_ends_at` (timestamp): 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_at` (timestamp, nullable): When the period was paid. - `paused_at` (timestamp, nullable): Reserved for paused periods. Always null. - `in_force` (boolean): `false` for an [upgrade](https://abuna.app/docs/api/subscriptions.md#upgrades)'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_at` (timestamp): When the period was created, in Unix seconds. **The billing period object** ```json { "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`](https://abuna.app/docs/api/apps.md#object), 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** - `id` (string): Unique identifier for the invoice. - `app_id` (string): The app that issued the invoice. - `period_id` (string): The billing period the invoice bills. - `subscription_id` (string): The subscription the invoice belongs to. - `number` (string): The invoice number, like `MYST-000124`. See [invoice numbers](https://abuna.app/docs/api/invoices-and-payments.md#invoice-numbers). - `status` (string): `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](https://abuna.app/docs/api/subscriptions.md#late-payments). - `kind` (string): `period` for a billing period, or `plan_change` for the first period of an upgrade. See [Upgrades](https://abuna.app/docs/api/subscriptions.md#upgrades). - `amount` (integer): The amount due, in the currency's smallest unit. - `credit` (integer): The unused time of the previous period taken off the price. `0` unless `kind` is `plan_change`. - `currency` (string): The price's currency: `XAF`, `XOF` or `USD`. - `item_label` (string): The price's name. - `buyer_name` (string, nullable): The customer's name. - `buyer_email` (string, nullable): The customer's email address. - `seller_name` (string): The app's name. - `period_start` (timestamp): When the billed period starts. - `period_end` (timestamp): When the billed period ends. - `due_at` (timestamp): The pay-by date. - `created_at` (timestamp): When the invoice was issued, in Unix seconds. - `paid_at` (timestamp, nullable): When the invoice was paid. - `voided_at` (timestamp, nullable): When the invoice was voided. Null again once a late payment makes it paid. - `discount` (integer): What the invoice's coupon took off it, in the currency's smallest unit. `0` without one. `amount` is already after it. - `coupon_id` (string, nullable): The [coupon](https://abuna.app/docs/api/coupons.md#object) that took the discount off. Null without one. - `promotion_code_id` (string, nullable): The promotion code that brought the coupon. Null when you applied the coupon directly, without a code. **The invoice object** ```json { "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](https://abuna.app/docs/amounts-currencies-and-timestamps.md#paying-in-fcfa). **Attributes** - `id` (string): Unique identifier for the payment. - `app_id` (string): The app the payment belongs to. - `period_id` (string): The billing period the payment is for. - `driver` (string): The payment provider, like `pawapay`. `abuna` for a payment through [Abuna payments](https://abuna.app/docs/guides/payment-providers.md#abuna-payments), `sandbox` for a simulated Test payment, and `manual` for a payment you [marked paid](https://abuna.app/docs/api/invoices-and-payments.md#mark-paid). - `provider` (string): The network the provider charged, like `MTN_MOMO_CMR`. `manual` for a payment you marked paid. - `provider_reference` (string, nullable): The provider's own ID for the charge. - `amount` (integer): The amount charged, in the currency's smallest unit. - `currency` (string): The currency charged. For mobile money, the network's: `XAF` or `XOF`. For a payment you [marked paid](https://abuna.app/docs/api/invoices-and-payments.md#mark-paid), the invoice's currency, with no conversion. - `original_amount` (integer, nullable): The invoice's amount, in its currency's smallest unit. Null on payments made before 13 November 2026. - `original_currency` (string, nullable): The invoice's currency: `XAF`, `XOF` or `USD`. Null on payments made before 13 November 2026. - `exchange_rate` (number, nullable): 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_bps` (integer, nullable): 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_at` (timestamp, nullable): 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. - `status` (string): `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`](https://abuna.app/docs/api/events.md#invoice-payment-failed). - `message` (string, nullable): 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`](https://abuna.app/docs/api/events.md#invoice-payment-failed). Null when there's no note. - `created_at` (timestamp): When the payment started, in Unix seconds. - `fee` (integer, nullable): 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](https://abuna.app/docs/guides/payment-providers.md#abuna-payments), it is Abuna's 3.5% fee instead, rounded down to the whole franc, set once the payment succeeds. - `net` (integer, nullable): For a payment through [Abuna payments](https://abuna.app/docs/guides/payment-providers.md#abuna-payments), what you receive: `amount` minus `fee`, set once the payment succeeds. Null for every other payment. - `session_id` (string, nullable): The session used to make this payment, or null for a payment made another way. - `note` (string, nullable): For a payment you marked paid, the note you gave about how the customer paid. Customers never see it. Null otherwise. - `marked_by_user_id` (string, nullable): For a payment marked paid from the dashboard, the ID of the team member who marked it. Null otherwise. - `marked_by_api_key_id` (string, nullable): For a payment marked paid with a secret key, the ID of that key. Null otherwise. - `method_label` (string): The network's name, in words. `Paid outside Abuna` for a payment you marked paid. **The payment object** ```json { "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** ```json { "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** - `id` (string): Unique identifier for the invoice. - `number` (string): The invoice number, like `MYST-000124`. See [invoice numbers](https://abuna.app/docs/api/invoices-and-payments.md#invoice-numbers). - `status` (string): `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](https://abuna.app/docs/api/subscriptions.md#late-payments). - `overdue` (boolean): `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. - `kind` (string): `period` or `plan_change`, as on the [invoice object](https://abuna.app/docs/api/invoices-and-payments.md#invoice-object). - `amount` (integer): The amount due, in the currency's smallest unit. - `credit` (integer): The unused time taken off the price, as on the invoice object. - `currency` (string): The price's currency: `XAF`, `XOF` or `USD`. - `item_label` (string): The price's name. - `buyer_name` (string, nullable): The customer's name. - `buyer_email` (string, nullable): The customer's email address. - `subscription_id` (string): The subscription the invoice belongs to. - `customer_id` (string): The subscription's customer. - `period_start` (timestamp): When the billed period starts. - `period_end` (timestamp): When the billed period ends. - `due_at` (timestamp): 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](https://abuna.app/docs/api/invoices-and-payments.md#invoice-object), which is set when the invoice is issued. - `created_at` (timestamp): When the invoice was issued, in Unix seconds. - `paid_at` (timestamp, nullable): When the invoice was paid. - `voided_at` (timestamp, nullable): When the invoice was voided. Null again once a late payment makes it paid. - `discount` (integer): What the invoice's coupon took off it, as on the invoice object. - `coupon_id` (string, nullable): The coupon that took the discount off, as on the invoice object. - `promotion_code_id` (string, nullable): The promotion code that brought the coupon, as on the invoice object. **The invoice summary object** ```json { "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** - `status` (string): `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. - `search` (string): Part of the invoice number, buyer name or buyer email. Ignores case. - `from` (timestamp): Only invoices issued at or after this time, in Unix seconds. - `to` (timestamp): Only invoices issued before this time, in Unix seconds. - `customer_id` (string): Only invoices for this customer. - `limit` (integer): How many invoices to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. **Response attributes** - `items` (array): The page's [invoices](https://abuna.app/docs/api/invoices-and-payments.md#invoice-summary). Empty when nothing matches. - `next_cursor` (string, nullable): 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: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?status=overdue&limit=50", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Response** ```json { "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** - `invoice` (object): The [invoice summary object](https://abuna.app/docs/api/invoices-and-payments.md#invoice-summary). - `pay_url` (string, nullable): The pay link for the billing period. It is null once the invoice is paid or void, or when the subscription is canceled. - `invoice_url` (string): A link to the customer's invoice page, which also shows paid and void invoices. It expires after 7 days. - `timeline` (array): What happened to the invoice, oldest first. Events in the same second come in the order below. - `type` (string): `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. - `at` (timestamp): When it happened, in Unix seconds. For a message, when it was sent, or created if it isn't sent yet. - `notice` (object): On a `notice` event: the [notice object](https://abuna.app/docs/api/notices.md#object). Its `recipient` is empty for Telegram. - `payment` (object): On a `payment` event: the [payment object](https://abuna.app/docs/api/invoices-and-payments.md#payment-object). Its `status` says how the attempt ended. - `reminder` (object): On a `reminder` event: an object with `kind`, one of `renewal_upcoming`, `payment_overdue` or `payment_final_notice`. > **Note:** In Live mode a reminder shows as the messages it sent, not as a `reminder` event. Test invoices keep no messages, so they show `reminder` events instead. Returns `200`. If the app has no invoice with that ID, returns `404` with code `not_found`. **GET /v1/apps/{appID}/invoices/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", { headers: { Authorization: "Bearer sk_test_..." }, }); const detail = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", headers={"Authorization": "Bearer sk_test_..."}, ) detail = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $detail = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var detail map[string]any json.NewDecoder(res.Body).Decode(&detail) ``` **Response** ```json { "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` 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](https://abuna.app/docs/api/sessions.md#create-payment). > **Note:** This works even while the app is read-only, so customers who owe you can still pay. **Response attributes** - `status` (string): `succeeded`, or `pending` while the customer approves the charge on their phone. - `paid` (boolean): `true` when `status` is `succeeded`. - `period` (object): The invoice's [billing period](https://abuna.app/docs/api/invoices-and-payments.md#period-object). 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](https://abuna.app/docs/api/customers.md#update), or send them a [payment session](https://abuna.app/docs/api/sessions.md#create-payment), 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`](https://abuna.app/docs/api/events.md#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`](https://abuna.app/docs/api/events.md#invoice-paid) before you refund or cancel anything. **POST /v1/apps/{appID}/invoices/{id}/charge** cURL: ```bash curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const charge = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", headers={"Authorization": "Bearer sk_test_..."}, ) charge = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $charge = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var charge map[string]any json.NewDecoder(res.Body).Decode(&charge) ``` **Response** ```json { "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` 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. > **Note:** This works even while the app is read-only, so you can still record what customers paid you. **Parameters** - `note` (string, required): 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** - `status` (string): Always `succeeded`. - `paid` (boolean): Always `true`. - `period` (object): The invoice's [billing period](https://abuna.app/docs/api/invoices-and-payments.md#period-object), now paid. - `payment` (object): The recorded [payment](https://abuna.app/docs/api/invoices-and-payments.md#payment-object): 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: ```bash 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" }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "cash-V2nC8xEi", }, body: JSON.stringify({ note: "Paid cash at the shop, receipt 0042", }), }); const marked = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "cash-V2nC8xEi"}, json={ "note": "Paid cash at the shop, receipt 0042", }, ) marked = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: cash-V2nC8xEi"], CURLOPT_POSTFIELDS => json_encode([ "note" => "Paid cash at the shop, receipt 0042", ]), CURLOPT_RETURNTRANSFER => true, ]); $marked = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "note": "Paid cash at the shop, receipt 0042", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/mark-paid", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "cash-V2nC8xEi") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var marked map[string]any json.NewDecoder(res.Body).Decode(&marked) ``` **Response** ```json { "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" } } ```