API Subscription

Gérez vos abonnements récurrents via API. Solution SaaS complète avec facturation automatique, relances intelligentes et analytics avancés.

🚀 Cas d'usage

• Plateformes SaaS - Abonnements mensuels/annuels
• Services de streaming - Accès récurrent au contenu
• E-learning - Accès aux cours par abonnement
• Applications mobiles - Premium subscriptions

Authentification

Utilisez votre clé API pour authentifier vos requêtes. Incluez-la dans l'en-tête Authorization.

curl https://api.geniuspay.ci/v1/merchant/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"

Démarrage Rapide

1️⃣ Créer un abonnement

curl -X POST https://api.geniuspay.ci/v1/merchant/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "phone": "+2250123456789",
      "name": "Jean Kouassi"
    },
    "plan_name": "Premium",
    "amount": 5000,
    "billing_cycle": "monthly"
  }'

2️⃣ Vérifier le statut

curl https://api.geniuspay.ci/v1/merchant/subscriptions/{uuid}/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Créer un abonnement

POST /v1/merchant/subscriptions

Paramètres

Paramètre	Type	Description
`customer.phone`	string	Téléphone du client (requis)
`customer.name`	string	Nom du client
`plan_name`	string	Nom du plan (requis)
`amount`	number	Montant en XOF (requis)
`billing_cycle`	string	daily, weekly, monthly, quarterly, yearly
`trial_days`	number	Nombre de jours d'essai gratuit

Réponse

{
  "success": true,
  "data": {
    "id": "sub_abc123xyz",
    "customer": {
      "phone": "+2250123456789",
      "name": "Jean Kouassi"
    },
    "plan_name": "Premium",
    "amount": 5000,
    "currency": "XOF",
    "billing_cycle": "monthly",
    "status": "active",
    "next_billing_date": "2026-03-10",
    "created_at": "2026-02-10T01:00:00Z"
  }
}

Lister les abonnements

GET /v1/merchant/subscriptions

Paramètres de requête

status - Filtrer par statut (active, paused, cancelled, etc.)
customer_phone - Rechercher par téléphone
billing_cycle - Filtrer par cycle
per_page - Nombre par page (max: 100)

curl "https://api.geniuspay.ci/v1/merchant/subscriptions?status=active&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Vérifier le statut

GET /v1/merchant/subscriptions/{uuid}/status

💡 Astuce: Utilisez cet endpoint pour vérifier si un client a accès à votre service.

Réponse

{
  "success": true,
  "data": {
    "is_active": true,
    "status": "active",
    "status_label": "Actif",
    "next_billing_date": "2026-03-10",
    "days_until_next_billing": 28,
    "is_trialing": false
  }
}

Annuler un abonnement

POST /v1/merchant/subscriptions/{uuid}/cancel

Paramètres

cancel_immediately - true pour annulation immédiate, false pour fin de cycle
reason - Raison de l'annulation (optionnel)

curl -X POST https://api.geniuspay.ci/v1/merchant/subscriptions/{uuid}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_immediately": false,
    "reason": "Service no longer needed"
  }'

Acheter des tokens

POST /v1/merchant/notification-tokens/purchase

💰 Tarifs: SMS = 25 XOF • Email = 10 XOF • Bonus 10% si ≥ 1000 tokens

curl -X POST https://api.geniuspay.ci/v1/merchant/notification-tokens/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token_type": "sms",
    "quantity": 100,
    "payment_method": "balance"
  }'

Statistiques

GET /v1/merchant/subscriptions/stats

Réponse

{
  "success": true,
  "data": {
    "subscriptions": {
      "total_subscriptions": 150,
      "active_subscriptions": 120,
      "past_due_subscriptions": 5
    },
    "revenue": {
      "mrr": 600000,
      "arr": 7200000,
      "monthly_revenue": 580000
    },
    "growth": {
      "new_this_month": 12,
      "cancelled_this_month": 3,
      "net_growth": 9
    },
    "churn_rate": 2.5
  }
}

Webhooks

Recevez des notifications en temps réel pour les événements d'abonnement.

Événements disponibles

subscription.created

Un abonnement a été créé

subscription.payment_succeeded

Un paiement a réussi

subscription.payment_failed

Un paiement a échoué

subscription.past_due

Un abonnement est en retard de paiement

subscription.cancelled

Un abonnement a été annulé

Format du payload

{
  "event": "subscription.payment_succeeded",
  "timestamp": "2026-02-10T01:00:00Z",
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "customer": {
        "phone": "+2250123456789",
        "name": "Jean Kouassi"
      },
      "plan_name": "Premium",
      "amount": 5000,
      "status": "active"
    }
  }
}

Codes d'erreur

Code	Message
`SUBSCRIPTION_NOT_FOUND`	Abonnement introuvable
`SUBSCRIPTION_CREATE_FAILED`	Échec de création
`INSUFFICIENT_TOKENS`	Tokens insuffisants