Getting started
Quickstart
In Test mode, create a product and a price, send a customer to checkout, and receive the webhook.
This guide takes you from a first checkout to a working subscription in Test mode, where no money moves. You create a product and a price, send a customer to checkout, pay with the Abuna simulator, and receive the webhook.
From there, Abuna runs the billing: it sends each renewal invoice with a pay link, reminds the customer, sends receipts, and cancels a subscription that stays unpaid. Your server only handles the webhook.
Get your Test key
Sign up and create an app in the dashboard. Abuna then shows a secret key and a webhook signing secret for Test and for Live. It shows them only once, so save them.
Open the app in Test mode, then Settings, then API keys, and copy the app ID. Use that ID in every path and the sk_test_ key in the Authorization header. The examples use the app ID 8ddhXCDW.
Lost a key? In Settings, open API keys and create a new one.
Create a product
A product is what you sell.
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"name": "Pro plan"}'{
"id": "pR4dWx9K",
"app_id": "8ddhXCDW",
"name": "Pro plan",
"slug": "pro-plan",
"created_at": 1727600000
}Create a price
Pass the product ID from the last response. This price charges FCFA 5,000 every month. Amounts are integers in the currency's smallest unit.
curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{"product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month"}'{
"id": "Zt6YbN3q",
"product_id": "pR4dWx9K",
"name": "Monthly",
"currency": "XAF",
"amount": 5000,
"interval": "month",
"interval_count": 1,
"created_at": 1727600000,
"archived_at": null,
"pending_change": null
}Set your webhook URL
In the dashboard, open Webhooks in Test mode and set your webhook URL. It must be a public https URL. Only a team owner can set it, and only from the dashboard, not with a secret key. Keep Recommended selected under the URL: it has every event this guide handles. See Choose your events.
To receive events on your own machine, run your server on port 3000 and open a tunnel to it. This command prints a public https URL that forwards to your machine. Use that URL, plus your webhook path, as the webhook URL.
cloudflared tunnel --url http://localhost:3000Install cloudflared first, for example with brew install cloudflared on macOS. Cloudflare's downloads page has it for Windows and Linux.
Abuna records events even with no webhook URL set, so you can skip this step and read them from the API later.
Create a checkout session
A checkout session is a checkout page for one customer. Create it with type checkout, from your server with your secret key, never from a browser. Put your own user ID in metadata, so the webhook tells you who paid. Create a checkout session lists every field.
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"type": "checkout",
"price_id": "Zt6YbN3q",
"success_url": "http://localhost:3000/welcome",
"metadata": {"user_id": "42"}
}'{
"id": "A4kN1oSs",
"type": "checkout",
"status": "open",
"url": "https://app.abuna.app/checkout/7f2c9e4a1b8d3f6e0c5a9d2b7e4f1a8c3d6b",
"success_url": "http://localhost:3000/welcome",
"cancel_url": null,
"return_url": null,
"metadata": {
"user_id": "42"
},
"customer_id": null,
"price_id": "Zt6YbN3q",
"subscription_id": null,
"invoice_id": null,
"plan_offer_id": null,
"at_period_end": null,
"updates_channel": "ask",
"upgrade_timing": "now",
"expires_at": 1727686400,
"completed_at": null,
"created_at": 1727600000
}The session lasts 24 hours. In Test mode, the success URL can be an http URL on localhost. Live mode needs https.
Send the customer to checkout
Redirect the customer to the session's url. They enter their email, and their name if they want. Abuna creates the customer and a pending subscription, then shows the pay step on the same page, where they enter the phone number they pay from. In Test mode, the Abuna simulator asks how the payment should end. Pick Successful payment.
Once paid, the subscription is active and the session is completed. The done screen links back to your success URL, with session_id and subscription_id added to it. The Sessions guide covers prefilling the customer, the return, expiry, and retries.
Or use a checkout link
To sell without writing code, share a checkout link. Open the product in the dashboard and copy the link next to the price. It looks like this, with your publishable key at the end:
https://app.abuna.app/web/checkout/Zt6YbN3q?publishkey=pk_test_...Anyone with the link can subscribe, so you can put it on a page or in a message. It carries no metadata, so Abuna can't tell you which of your users paid. When you need to know, create a checkout session instead. Once paid, the checkout links back to your app's success URL. Set it in Settings, under General.
Or subscribe a customer from your server
To skip checkout, create the customer yourself. Send an email address and a phone number with its country code. Put your own user ID in metadata, so you can link the customer back to your user.
curl https://api.abuna.app/v1/apps/8ddhXCDW/customers \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Ana N.",
"email": "ana@example.com",
"phone_number": "+237671234567",
"metadata": {"user_id": "42"}
}'{
"app_id": "qhf83tDc",
"created_at": 1794780106,
"email": "ana@example.com",
"id": "uRyKEuNE",
"language": null,
"metadata": {
"user_id": "42"
},
"name": "Ana N.",
"phone_number": "+237671234567",
"updates": {
"channel": null,
"email": {
"status": "active"
},
"telegram": {
"connect_url": null,
"connected_at": null,
"status": "off"
},
"whatsapp": {
"connect_url": null,
"connected_at": null,
"status": "off"
}
}
}Then start the subscription with the customer and price IDs. Put your user ID in its metadata too. Subscription and invoice events carry it, so your webhook handler can find the user. The response holds the pending subscription and its first billing period, the period.
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"metadata": {"user_id": "42"}
}'{
"period": {
"created_at": 1794780106,
"ends_at": 1797372106,
"grace_period_ends_at": 1795039306,
"id": "s2inWsTI",
"in_force": true,
"paid_at": null,
"paused_at": null,
"pay_token": "0eb654243432023fc096aea7c930a56d3a9b",
"period_index": 0,
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"subscription_id": "pN7lZK8d"
},
"subscription": {
"activated_at": null,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": null,
"current_period_start": null,
"customer_id": "uRyKEuNE",
"discount": null,
"ended_reason": null,
"id": "pN7lZK8d",
"manage_token": "300a8bcd3618051e1cb589fe3e946b3e8c33",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "pending",
"trial_ends_at": null
}
}Abuna emails the customer a pay link for this invoice. In Test mode it records the email as an event instead of sending it. The customer has until grace_period_ends_at to pay, or Abuna cancels the subscription.
Pay the first invoice
Find the open invoice for the customer. It is the first item.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?customer_id=Cu5tM8rA&status=open" \
-H "Authorization: Bearer sk_test_..."Charge the invoice from your server with its id. In Test mode the simulated payment succeeds and moves no money. In Live mode the customer approves the payment on their phone.
curl -X POST https://api.abuna.app/v1/apps/8ddhXCDW/invoices/V2nC8xEi/charge \
-H "Authorization: Bearer sk_test_..."{
"paid": true,
"period": {
"created_at": 1794780106,
"ends_at": 1797372106,
"grace_period_ends_at": 1795039306,
"id": "0kYPFwxJ",
"in_force": true,
"paid_at": 1794780106,
"paused_at": null,
"pay_token": "dc687f8ef2320fd275609300f241120a681b",
"period_index": 0,
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"subscription_id": "wTiODxvH"
},
"status": "succeeded"
}The subscription is now active.
Receive the webhook
Whichever way the customer subscribed, Abuna records these events:
subscription.createdandinvoice.createdwhen the subscription starts.invoice.paidandsubscription.paidwhen the first payment succeeds.session.completedat the same moment, if the customer paid through a checkout session.
For a checkout session, grant access when session.completed arrives. It carries your metadata and the new subscription_id and customer_id. For a checkout link or a subscription you started from your server, grant access on subscription.paid, which Abuna records once per subscription, when it turns active.
Each request carries an X-Abuna-Signature header. Check it before you trust the body, as Receiving webhooks shows.
{
"created_at": 1794780106,
"data": {
"completed_at": 1794780106,
"customer_id": "GzeUZeSV",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"session_id": "l6wWNcdC",
"subscription": {
"activated_at": 1794780106,
"app_id": "qhf83tDc",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": 1794780106,
"current_period_end": 1797372106,
"current_period_start": 1794780106,
"customer_id": "GzeUZeSV",
"discount": null,
"ended_reason": null,
"id": "wTiODxvH",
"manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0",
"metadata": {
"user_id": "42"
},
"price_id": "IaFQHLTL",
"starts_at": 1794780106,
"status": "active",
"trial_ends_at": null
},
"subscription_id": "wTiODxvH",
"type": "checkout",
"updates": {
"channel": null,
"email": {
"status": "active"
},
"telegram": {
"connect_url": null,
"connected_at": null,
"status": "off"
},
"whatsapp": {
"connect_url": null,
"connected_at": null,
"status": "off"
}
}
},
"environment": "test",
"id": "01M7GKP459FJ1SRX8QSW721E8Y",
"type": "session.completed"
}To see what happened without a webhook URL, list the app's events. The newest come first, in items. Each one has the same shape as the webhook body.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=session.completed" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "01J9ZQ8E1F2G3H4J5K6M7N8P9Q",
"type": "session.completed",
"environment": "test",
"created_at": 1727600600,
"data": {
"session_id": "A4kN1oSs",
"type": "checkout",
"subscription_id": "x9QbL2sK",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"metadata": {
"user_id": "42"
},
"completed_at": 1727600600,
"updates": {
"channel": null,
"email": {
"status": "active"
},
"telegram": {
"status": "off",
"connected_at": null,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
},
"subscription": {
"id": "x9QbL2sK",
"app_id": "8ddhXCDW",
"customer_id": "Cu5tM8rA",
"price_id": "Zt6YbN3q",
"status": "active",
"starts_at": 1727600000,
"activated_at": 1727600100,
"trial_ends_at": null,
"canceled_at": null,
"cancel_at": null,
"cancel_at_period_end": false,
"current_period_start": 1727600000,
"current_period_end": 1730192000,
"ended_reason": null,
"metadata": {
"user_id": "42"
},
"created_at": 1727600000,
"manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b",
"discount": null
}
}
}
],
"next_cursor": null
}After the first payment
You don't call Abuna again to renew. Before each renewal date, Abuna sends the customer an invoice with a pay link. You set how many days customers have to pay, from 1 to 14. If a renewal is still unpaid after that, Abuna cancels the subscription and tells the customer.
Each step arrives as an event. subscription.renewed and invoice.created come with the renewal invoice, and invoice.paid when the customer pays. If the renewal date passes unpaid, you get subscription.past_due, then subscription.canceled if it stays unpaid. Next, read Customer messages for reminders and channels, then Going Live checklist.
Next steps
- SessionsSend a customer from your app to subscribe, pay, change plan or cancel, bring them back, and know for sure when they're done.
- Receiving webhooksReceive events on your server and verify that Abuna sent them.
- Test mode and Live modeBuild against Test data with the Abuna simulator or provider sandboxes, then switch to Live with the same code.
- Going Live checklistEverything to check before you take real payments.