Skip to content
ABUNA
DocsQuickstart

Getting started

Quickstart

In Test mode, create a product and a price, send a customer to checkout, and receive the webhook.

View as Markdown

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.

POST /v1/apps/{appID}/products
curl https://api.abuna.app/v1/apps/8ddhXCDW/products \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Pro plan"}'
Response
{
  "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.

POST /v1/apps/{appID}/prices
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"}'
Response
{
  "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.

Open a tunnel to port 3000
cloudflared tunnel --url http://localhost:3000

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

POST /v1/apps/{appID}/sessions
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"}
  }'
Response
{
  "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.

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:

Checkout link
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.

POST /v1/apps/{appID}/customers
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"}
  }'
Response
{
  "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.

POST /v1/apps/{appID}/subscriptions
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"}
  }'
Response
{
  "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.

GET /v1/apps/{appID}/invoices
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.

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
{
  "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.created and invoice.created when the subscription starts.
  • invoice.paid and subscription.paid when the first payment succeeds.
  • session.completed at 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.

session.completed webhook body
{
  "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.

GET /v1/apps/{appID}/events
curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=session.completed" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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