> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des abonnements

> Choisissez un plan, abonnez-vous via le paiement, gérez les modules complémentaires et gérez l'annulation à l'aide de l'API ou de la console.

Vous pouvez gérer l'intégralité de votre cycle de facturation via l'API ou la console. Ce guide explique comment lister les plans, estimer les coûts, créer une session de paiement, vérifier votre abonnement, ajouter des modules complémentaires et annuler si nécessaire.

## Prérequis

* Un compte Truthlocks avec un locataire actif.
* Une clé API avec des permissions de facturation. Voir [Clés API](https://docs.truthlocks.com/fr/api-reference/api-keys/create.md) pour en créer une.

## Choisir un plan

Truthlocks propose cinq niveaux de plan. Utilisez le point de terminaison des plans pour récupérer le catalogue complet — il s'agit d'un point de terminaison public qui ne nécessite pas d'authentification.

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/plans
```

```json theme={null}
[
  {
    "key": "plan_developer",
    "name": "Developer",
    "price": 0,
    "currency": "USD",
    "interval": "month",
    "features": ["500 mints/month", "Plan-dependent verifications", "Community support"],
    "highlight": false
  },
  {
    "key": "plan_starter",
    "name": "Starter",
    "price": 29,
    "currency": "USD",
    "interval": "month",
    "features": ["Higher quotas", "3 webhook endpoints", "Priority processing"],
    "highlight": true
  }
]
```

Voir [aperçu de la facturation](https://docs.truthlocks.com/fr/billing/overview.md#plan-tiers) pour une comparaison de tous les plans.

## Estimer vos coûts

Avant de vous abonner, utilisez le point de terminaison d'estimation pour obtenir une recommandation de plan basée sur votre utilisation prévue. Il s'agit également d'un point de terminaison public.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "expected_verifications_monthly": 10000,
    "team_seats": 5,
    "webhook_endpoints_needed": 5,
    "storage_gb": 10
  }'
```

La réponse comprend un plan recommandé et un total mensuel estimé. Pour une ventilation des coûts par poste, utilisez plutôt le point de terminaison [facture projetée](https://docs.truthlocks.com/fr/api-reference/billing/projected-invoice.md).

## Vérifiez vos tarifs actuels

Les tarifs effectifs par utilisation de votre locataire dépendent de votre grille tarifaire et de votre région. Récupérez-les avec :

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/rates \
  -H "X-API-Key: tl_live_..."
```

La réponse inclut les tarifs de base et les ajustements de prix régionaux :

```json theme={null}
{
  "rate_card": { "id": "rc_default", "name": "Standard Rates", "currency": "USD" },
  "items": [
    { "metric": "attestations.mint", "unit_price": 25, "volume_min": 0, "volume_max": 0 },
    { "metric": "verifications", "unit_price": 10, "volume_min": 0, "volume_max": 0 }
  ],
  "is_default": true,
  "regional_rates": {
    "region": "TIER_1",
    "multiplier": 1.0,
    "mint_rate_cents": 25,
    "verify_rate_cents": 10
  }
}
```

> [!NOTE]
>
> Si votre organisation a une carte tarifaire personnalisée attribuée par un administrateur de plateforme, ces tarifs apparaissent ici au lieu des valeurs par défaut.

## S'abonner à un plan

Créez une session de paiement pour démarrer ou mettre à niveau votre abonnement. Le service de facturation sélectionne automatiquement le fournisseur de paiement approprié pour votre région.

**1. Créer une session de paiement**

Appelez le point de terminaison de paiement avec le plan que vous souhaitez et les URL de redirection :

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/checkout \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_key": "STARTER",
    "success_url": "https://yourapp.com/billing?success=true",
    "cancel_url": "https://yourapp.com/billing?canceled=true"
  }'
```

La réponse contient un `checkout_url` hébergé par le fournisseur de paiement.

**2. Rediriger vers la caisse**

Envoyez l'utilisateur à `checkout_url` pour finaliser le paiement.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/billing/checkout", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_key: "STARTER",
    success_url: `${window.location.origin}/billing?success=true`,
    cancel_url: `${window.location.origin}/billing?canceled=true`,
  }),
});
const { checkout_url } = await res.json();
window.location.href = checkout_url;
```

**3. Confirmer l'abonnement**

Après le paiement, vérifiez que l'abonnement est actif :

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/subscription \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": false
}
```

> [!TIP]
>
> Vous pouvez éventuellement passer un paramètre `provider` (`stripe`, `paystack`, ou `flutterwave`) pour remplacer le routage automatique basé sur la région. Voir [routage du fournisseur](https://docs.truthlocks.com/fr/billing/provider-routing.md) pour plus de détails.

## Attacher des modules complémentaires

Les modules complémentaires étendent votre plan avec des capacités supplémentaires. Attachez-les via l'API :

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "addon_key": "addon_seat",
    "quantity": 2
  }'
```

Si l'add-on a un prix, la réponse inclut un `checkout_url` pour effectuer le paiement. Les add-ons gratuits s'activent immédiatement.

> [!NOTE]
>
> Les prix des modules complémentaires s'ajustent automatiquement en fonction du pays de facturation de votre organisation. Les locataires des régions à faible coût paient un tarif réduit — par exemple, le pack de conformité coûte 149,50 $/mois au Nigeria (multiplicateur de 0,5x) au lieu du prix de base de 299 $. Consultez la [tarification régionale des modules complémentaires](https://docs.truthlocks.com/fr/billing/overview.md#regional-add-on-pricing) pour le tableau complet des niveaux.

Pour supprimer un module complémentaire :

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"addon_key": "addon_seat"}'
```

Voir [gérer les modules complémentaires](https://docs.truthlocks.com/fr/api-reference/billing/addons.md) pour le catalogue complet des modules complémentaires et les détails de la réponse.

## Surveiller l'utilisation

Suivez votre consommation du cycle de facturation actuel pour rester dans les limites de votre plan :

```bash theme={null}
curl https://api.truthlocks.com/v1/billing/usage \
  -H "X-API-Key: tl_live_..."
```

Pour vérifier si une opération spécifique est dans le quota avant de l'exécuter :

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/limits/check \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metric": "attestations.mint", "amount": 1}'
```

## Ouvrir le portail de facturation

Redirigez les utilisateurs vers le portail libre-service de leur fournisseur de paiement pour mettre à jour les méthodes de paiement, consulter les factures ou gérer leur abonnement :

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/portal \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.com/settings/billing"
  }'
```

La réponse inclut une `portal_url`. Redirigez l'utilisateur vers cette URL. Les sessions du portail expirent rapidement, alors générez une nouvelle URL à chaque fois.

## Annuler un abonnement

Pour annuler, appelez le point de terminaison d'annulation. L'annulation prend effet à la fin de la période de facturation en cours — vous conservez un accès complet jusqu'à cette date.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/cancel \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "status": "active",
  "plan_key": "plan_starter",
  "current_period_end": "2026-05-01T00:00:00Z",
  "cancel_at_period_end": true
}
```

Une fois la période terminée, votre compte est rétrogradé au plan Développeur (gratuit). Pour vous réabonner, créez une nouvelle [session de paiement](https://docs.truthlocks.com/fr/api-reference/billing/checkout.md).

> [!WARNING]
>
> Vous ne pouvez pas annuler une annulation via l'API. Pour reprendre votre abonnement, vous devez repasser par le processus de paiement.

## Lié

> [card] [Aperçu de la facturation](https://docs.truthlocks.com/billing/overview.md)
>
> Planifiez les niveaux, les tarifs, les droits et les add-ons.

> [card] [Routage du fournisseur](https://docs.truthlocks.com/billing/provider-routing.md)
>
> Comment les paiements sont acheminés par région.

> [card] [Référence de l'API de facturation](https://docs.truthlocks.com/api-reference/billing/config.md)
>
> Référence complète du point de terminaison de l'API de facturation.

> [card] [Droits](https://docs.truthlocks.com/api-reference/billing/entitlements.md)
>
> Vérifiez vos fonctionnalités et quotas actifs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.