Skip to content
ABUNA
S'inscrire
DocumentationDémarrage rapide

Pour commencer

Démarrage rapide

Créez un produit et un tarif, envoyez un client vers une session de paiement, et recevez le webhook, en mode Test.

Dans ce guide, vous créez un produit et un tarif en mode Test, envoyez un client vers une session de paiement, payez avec un paiement simulé et recevez le webhook. Aucun argent ne circule.

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 Réel. 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 tarif

Utilisez l'ID du produit de la dernière réponse. Ce tarif 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
}

Configurez votre endpoint de webhook

Dans le tableau de bord, ouvrez Webhooks en mode Test et définissez l'URL de votre endpoint. 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.

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 d'endpoint.

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 endpoint configuré, vous pouvez donc sauter cette étape et les lire plus tard depuis l'API.

Créez une session de paiement

Une session de paiement est une page hébergée pour un 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 de paiement 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,
  "expires_at": 1727686400,
  "completed_at": null,
  "created_at": 1727600000
}

La session dure 24 heures. En mode Test, l'URL de succès peut être une URL http sur localhost. Le mode Réel exige https.

Envoyez le client au paiement

Redirigez le client vers l'url de la session. Il saisit son nom, son e-mail et son numéro de téléphone. Abuna crée le client et un abonnement pending, puis affiche l'étape de paiement sur la même page. En mode Test, il vous demande quel résultat simulé utiliser. Choisissez Paiement réussi.

Une fois payé, l'abonnement est active et la session completed. L'écran de fin renvoie vers votre URL de succès, 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 de paiement. Ouvrez le produit dans le tableau de bord et copiez le lien à côté du tarif. Il ressemble à ceci, avec votre clé publiable à la fin :

Lien de paiement
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 de paiement. Une fois payé, la page de paiement renvoie vers l'URL de succès de votre application. Définissez-la dans Paramètres, sous Général.

Ou abonnez un client depuis votre serveur

Pour éviter le paiement, créez le client vous-même. Un client a besoin d'une adresse e-mail et d'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": "VyYjSLf1",
  "created_at": 1791143442,
  "email": "ana@example.com",
  "id": "bCEs1T9J",
  "language": null,
  "metadata": {
    "user_id": "42"
  },
  "name": "Ana N.",
  "phone_number": "+237671234567"
}

Démarrez ensuite l'abonnement avec les ID du client et du tarif. 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"
  }'
Réponse
{
  "period": {
    "created_at": 1791143442,
    "ends_at": 1793821842,
    "grace_period_ends_at": 1791402642,
    "id": "Y9mAh9OS",
    "in_force": true,
    "paid_at": null,
    "paused_at": null,
    "pay_token": "eacba2d9d70f3ad4ca2bbef2932f98ec557c",
    "period_index": 0,
    "price_id": "UKjuDVyN",
    "starts_at": 1791143442,
    "subscription_id": "ghVBHcxQ"
  },
  "subscription": {
    "activated_at": null,
    "app_id": "VyYjSLf1",
    "cancel_at": null,
    "canceled_at": null,
    "created_at": 1791143442,
    "current_period_end": null,
    "current_period_start": null,
    "customer_id": "bCEs1T9J",
    "ended_reason": null,
    "id": "ghVBHcxQ",
    "manage_token": "ead72992d218c59044fe99765b1d7c4db5ee",
    "metadata": {},
    "price_id": "UKjuDVyN",
    "starts_at": 1791143442,
    "status": "pending"
  }
}

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 annule 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ébite la facture depuis votre serveur avec son id. En mode Test, le paiement simulé réussit et ne déplace aucun argent. En mode Réel, il débite le numéro de téléphone du client via votre prestataire.

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": 1791143442,
    "ends_at": 1793821842,
    "grace_period_ends_at": 1791402642,
    "id": "tKhKXYjr",
    "in_force": true,
    "paid_at": 1791143442,
    "paused_at": null,
    "pay_token": "a5f9dabb70c03857e4ba6f53973b8f9a3690",
    "period_index": 0,
    "price_id": "UKjuDVyN",
    "starts_at": 1791143442,
    "subscription_id": "coRNVNUz"
  },
  "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 de paiement.

Pour une session de paiement, accordez l'accès quand session.completed arrive. Il porte votre metadata et les nouveaux subscription_id et customer_id. Pour un lien de paiement 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 corps, comme le montre Recevoir des webhooks.

Corps du webhook session.completed
{
  "created_at": 1791143442,
  "data": {
    "completed_at": 1791143442,
    "customer_id": "OljRiqBE",
    "metadata": {
      "user_id": "42"
    },
    "price_id": "UKjuDVyN",
    "session_id": "hFFoMabd",
    "subscription": {
      "activated_at": 1791143442,
      "app_id": "VyYjSLf1",
      "cancel_at": null,
      "canceled_at": null,
      "created_at": 1791143442,
      "current_period_end": 1793821842,
      "current_period_start": 1791143442,
      "customer_id": "OljRiqBE",
      "ended_reason": null,
      "id": "coRNVNUz",
      "manage_token": "d6f6ca3a8b285784aed37bd593bab9dea12e",
      "metadata": {
        "user_id": "42"
      },
      "price_id": "UKjuDVyN",
      "starts_at": 1791143442,
      "status": "active"
    },
    "subscription_id": "coRNVNUz",
    "type": "checkout"
  },
  "environment": "test",
  "id": "01M447FXSQV6CF386W50R34A5T",
  "type": "session.completed"
}

Pour voir ce qui s'est passé sans endpoint, listez les événements de l'application. Les plus récents viennent en premier, dans items. Chacun a la même forme que le corps 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,
        "subscription": {
          "id": "x9QbL2sK",
          "app_id": "8ddhXCDW",
          "customer_id": "Cu5tM8rA",
          "price_id": "Zt6YbN3q",
          "status": "active",
          "starts_at": 1727600000,
          "activated_at": 1727600100,
          "canceled_at": null,
          "cancel_at": null,
          "current_period_start": 1727600000,
          "current_period_end": 1730192000,
          "ended_reason": null,
          "metadata": {
            "user_id": "42"
          },
          "created_at": 1727600000,
          "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
        }
      }
    }
  ],
  "next_cursor": null
}

Étapes suivantes