Skip to content
ABUNA
DocumentationDémarrage rapide

Pour commencer

Démarrage rapide

En mode Test, créez un produit et un prix, envoyez un client vers la page d'abonnement et recevez le webhook.

Voir en Markdown

Ce guide vous mène d'un premier abonnement à un abonnement actif, en mode Test, où aucun argent ne circule. Vous créez un produit et un prix, envoyez un client sur la page d'abonnement, payez avec le simulateur Abuna et recevez le webhook.

Ensuite, Abuna gère la facturation : il envoie chaque facture de renouvellement avec un lien de paiement, rappelle au client de payer, envoie les reçus et résilie l'abonnement qui reste impayé. Votre serveur traite seulement le webhook.

Obtenez votre clé Test

Inscrivez-vous et créez une application dans le tableau de bord. Abuna affiche alors une clé secrète et un secret de signature de webhook pour Test et pour Production. Il ne les affiche qu'une seule fois, alors conservez-les.

Ouvrez l'application en mode Test, puis Paramètres, puis Clés d'API, et copiez l'ID de l'application. Utilisez cet ID dans chaque chemin et la clé sk_test_ dans l'en-tête Authorization. Les exemples utilisent l'ID de l'application 8ddhXCDW.

Vous avez perdu une clé ? Dans Paramètres, ouvrez Clés d'API et créez-en une nouvelle.

Créez un produit

Un produit est ce que vous vendez.

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"}'
Réponse
{
  "id": "pR4dWx9K",
  "app_id": "8ddhXCDW",
  "name": "Pro plan",
  "slug": "pro-plan",
  "created_at": 1727600000
}

Créez un prix

Utilisez l'ID du produit de la dernière réponse. Ce prix facture 5 000 FCFA par mois. Les montants sont des entiers dans la plus petite unité de la devise.

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"}'
Réponse
{
  "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
}

Configurez l'URL de votre webhook

Dans le tableau de bord, ouvrez Webhooks en mode Test et définissez l'URL de votre webhook. Elle doit être une URL https publique. Seul un propriétaire d'équipe peut la définir, et uniquement depuis le tableau de bord, pas avec une clé secrète. Gardez Recommandés sélectionné sous l'URL : il contient tous les événements que ce guide traite. Voyez Choisissez vos événements.

Pour recevoir des événements sur votre propre machine, exécutez votre serveur sur le port 3000 et ouvrez un tunnel vers lui. Cette commande affiche une URL https publique qui redirige vers votre machine. Utilisez cette URL, suivie du chemin de votre webhook, comme URL du webhook.

Ouvrir un tunnel vers le port 3000
cloudflared tunnel --url http://localhost:3000

Installez d'abord cloudflared, par exemple avec brew install cloudflared sur macOS. La page de téléchargement de Cloudflare le propose pour Windows et Linux.

Abuna enregistre les événements même sans URL de webhook, vous pouvez donc sauter cette étape et les lire plus tard depuis l'API.

Créez une session d'abonnement

Une session d'abonnement est une page d'abonnement pour un seul client. Créez-la avec type checkout, depuis votre serveur avec votre clé secrète, jamais depuis un navigateur. Placez votre propre ID d'utilisateur dans metadata, pour que le webhook vous indique qui a payé. Créer une session checkout liste tous les champs.

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"}
  }'
Réponse
{
  "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
}

La session dure 24 heures. En mode Test, l'URL de retour après paiement peut être une URL http sur localhost. Le mode Production exige https.

Envoyez le client sur la page d'abonnement

Redirigez le client vers l'url de la session. Il saisit son e-mail, et son nom s'il le souhaite. Abuna crée le client et un abonnement pending, puis affiche l'étape de paiement sur la même page, où il saisit le numéro de téléphone avec lequel il paie. En mode Test, le simulateur Abuna demande comment le paiement doit se terminer. Choisissez Successful payment.

Une fois payé, l'abonnement est active et la session completed. L'écran de fin renvoie vers votre URL de retour après paiement, avec session_id et subscription_id ajoutés. Le guide Sessions couvre le préremplissage du client, le retour, l'expiration et les nouvelles tentatives.

Pour vendre sans écrire de code, partagez un lien d'abonnement. Ouvrez le produit dans le tableau de bord et copiez le lien à côté du prix. Il ressemble à ceci, avec votre clé publiable à la fin :

Lien d'abonnement
https://app.abuna.app/web/checkout/Zt6YbN3q?publishkey=pk_test_...

Toute personne disposant du lien peut s'abonner, vous pouvez donc le placer sur une page ou dans un message. Il ne porte aucun metadata, Abuna ne peut donc pas vous dire lequel de vos utilisateurs a payé. Quand vous avez besoin de le savoir, créez plutôt une session d'abonnement. Une fois payé, la page d'abonnement renvoie vers l'URL de retour après paiement de votre application. Définissez-la dans Paramètres, sous Général.

Ou abonnez un client depuis votre serveur

Pour vous passer de la page d'abonnement, créez le client vous-même. Envoyez une adresse e-mail et un numéro de téléphone avec son indicatif pays. Placez votre propre ID d'utilisateur dans metadata, pour pouvoir rattacher le client à votre utilisateur.

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"}
  }'
Réponse
{
  "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"
    }
  }
}

Démarrez ensuite l'abonnement avec les ID du client et du prix. Placez aussi votre ID d'utilisateur dans son metadata. Les événements d'abonnement et de facture le portent, pour que votre gestionnaire de webhook retrouve l'utilisateur. La réponse contient l'abonnement pending et sa première période de facturation, la 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"}
  }'
Réponse
{
  "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 envoie au client un lien de paiement pour cette facture par e-mail. En mode Test, il enregistre l'e-mail comme événement au lieu de l'envoyer. Le client a jusqu'à grace_period_ends_at pour payer, sinon Abuna résilie l'abonnement.

Payez la première facture

Trouvez la facture ouverte du client. C'est le premier élément.

GET /v1/apps/{appID}/invoices
curl "https://api.abuna.app/v1/apps/8ddhXCDW/invoices?customer_id=Cu5tM8rA&status=open" \
  -H "Authorization: Bearer sk_test_..."

Débitez la facture depuis votre serveur avec son id. En mode Test, le paiement simulé réussit et ne déplace aucun argent. En mode Production, le client approuve le paiement sur son télé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_..."
Réponse
{
  "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"
}

L'abonnement est maintenant active.

Recevez le webhook

Quelle que soit la façon dont le client s'est abonné, Abuna enregistre ces événements :

  • subscription.created et invoice.created au démarrage de l'abonnement.
  • invoice.paid et subscription.paid lorsque le premier paiement réussit.
  • session.completed au même moment, si le client a payé via une session d'abonnement.

Pour une session d'abonnement, accordez l'accès quand session.completed arrive. Il porte votre metadata et les nouveaux subscription_id et customer_id. Pour un lien d'abonnement ou un abonnement que vous avez démarré depuis votre serveur, accordez l'accès sur subscription.paid, qu'Abuna enregistre une fois par abonnement, quand il devient actif.

Chaque requête porte un en-tête X-Abuna-Signature. Vérifiez-le avant de faire confiance au contenu, comme le montre Recevoir des webhooks.

Contenu du webhook session.completed
{
  "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"
}

Pour voir ce qui s'est passé sans URL de webhook, listez les événements de l'application. Les plus récents viennent en premier, dans items. Chacun a la même forme que le contenu du webhook.

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

Après le premier paiement

Vous n'appelez plus Abuna pour renouveler. Avant chaque date de renouvellement, Abuna envoie au client une facture avec un lien de paiement. Vous choisissez combien de jours vos clients ont pour payer, de 1 à 14. Si un renouvellement reste impayé au-delà, Abuna résilie l'abonnement et prévient le client.

Chaque étape arrive sous forme d'événement. subscription.renewed et invoice.created accompagnent la facture de renouvellement, puis invoice.paid quand le client paie. Si la date de renouvellement passe sans paiement, vous recevez subscription.past_due, puis subscription.canceled s'il reste impayé. Lisez ensuite Messages aux clients pour les rappels et les canaux, puis Avant de passer en production.

Étapes suivantes