Skip to content
ABUNA
S'inscrire
DocumentationEssais gratuits

Guides

Essais gratuits

Proposez un essai gratuit, accordez l'accès à partir des webhooks et encaissez le premier paiement à la fin de l'essai.

Voir en Markdown

Accordez un accès gratuit avant la première période payante, sans demander de paiement sur la page d'abonnement.

Définir un essai sur un prix

Créez un prix avec trial_days, un entier de 1 à 365. Cet exemple propose 14 jours gratuits, puis 5 000 FCFA par mois.

Créer un prix avec 14 jours d'essai
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",
    "trial_days": 14
  }'

Omettez trial_days ou envoyez null pour ne pas proposer d'essai. La durée ne peut plus changer après la création du prix. Créez un autre prix pour proposer une autre durée par défaut.

Envoyer le client vers la page d'abonnement

Créez une session checkout depuis votre serveur, puis envoyez le client vers son url. Remplacez les identifiants et la clé secrète de l'exemple par vos valeurs Test.

Créer une session avec l'essai du prix
curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-user-42-trial-1" \
  -d '{
    "type": "checkout",
    "price_id": "Zt6YbN3q",
    "customer_id": "Cu5tM8rA",
    "success_url": "https://example.com/subscribed?session_id={SESSION_ID}",
    "cancel_url": "https://example.com/plans",
    "metadata": {"user_id": "42"}
  }'

Le client confirme ses coordonnées, choisit ses rappels et accepte de commencer l'essai. Abuna lui envoie ensuite un code à 6 chiffres par e-mail, et l'essai commence quand il le saisit sur la page d'abonnement. D'ici là, aucun abonnement n'existe et aucun essai n'est utilisé. Aucun paiement n'est demandé. La session se termine et le client rejoint votre success_url, avec l'activation habituelle de la messagerie choisie.

Requête de session checkout ou d'abonnementDurée de l'essai
trial_days absentLa durée définie sur le prix.
trial_days: 1 à 365Cette durée remplace celle du prix.
trial_days: 0Pas d'essai. Le premier paiement habituel s'applique.

Démarrer un essai sans page d'abonnement

Pour un client existant, créez directement un abonnement. Cet exemple remplace la durée du prix par 7 jours.

Créer un abonnement avec 7 jours d'essai
curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: subscription-user-42-trial-1" \
  -d '{
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "trial_days": 7,
    "metadata": {"user_id": "42"}
  }'

L'abonnement démarre avec status: trialing. Son trial_ends_at indique la fin de l'essai en secondes Unix. Sans essai, ce champ vaut null.

Abonnement pendant un essai de 7 jours
{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "trialing",
  "starts_at": 1727600000,
  "activated_at": 1727600000,
  "trial_ends_at": 1728204800,
  "canceled_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "current_period_start": 1727600000,
  "current_period_end": 1728204800,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

Accorder l'accès à partir des webhooks

Vérifiez la signature du webhook avant d'utiliser un événement. Décidez de l'accès à partir de l'abonnement dans l'événement, pas du retour du navigateur.

  • subscription.created est envoyé au début de l'essai. Une session checkout envoie aussi session.completed. Accordez l'accès quand data.subscription.status vaut trialing ; data.subscription.trial_ends_at est la fin de l'essai.
  • subscription.paid est envoyé quand le client paie la première facture, pendant ou après l'essai.
  • subscription.trial_ending signale la fin prochaine de l'essai, selon le délai habituel des rappels de renouvellement de votre application. Si votre URL de webhook date d'avant les essais gratuits, activez d'abord cet événement : ouvrez Webhooks dans le tableau de bord et modifiez les Événements.
  • Gardez l'accès pour active et past_due. Retirez-le à la réception de subscription.canceled.

Le premier paiement

La première période payante commence à trial_ends_at, même si le client paie en avance. Abuna envoie sa facture et son lien de paiement selon le délai de renouvellement de votre application.

La date limite de paiement correspond normalement à la fin de l'essai plus grace_period_days, sans dépasser la fin de la période payante. Utilisez le due_at de la facture pour connaître la date exacte, y compris si la facture arrive plus tard.

Le client dispose de 3 jours par défaut ; vous pouvez choisir de 1 à 14 jours. Aucun prélèvement n'est automatique.

Si la facture reste impayée, les règles habituelles des renouvellements impayés s'appliquent, avec résiliation après la date limite de paiement.

Résilier pendant l'essai

Un client qui résilie pendant l'essai conserve l'accès jusqu'à sa fin. Toute première facture encore impayée est annulée, sans rien à payer. La résiliation programmée définit cancel_at à trial_ends_at.

Avec l'API de résiliation, at_period_end: true programme cette même fin. Omettez ce champ ou envoyez false pour retirer l'accès immédiatement.

Limites en Test et en Production

Les clients ayant un abonnement trialing, qui commence une fois leur e-mail confirmé, comptent dans la limite d'abonnés en production de votre équipe. Le mode Test n'a pas de limite d'abonnés.

Étapes suivantes