# Rechargement automatique de sous-compte (fournisseur de paiement personnalisé)

Si vous préférez gérer les paiements de crédit des sous-comptes via votre propre fournisseur plutôt que Stripe (virements bancaires, passerelles de paiement locales, systèmes de facturation personnalisés), la plateforme expose une paire webhook + API afin que vous puissiez exécuter vous-même l'intégralité du cycle de facturation et d'octroi. La présentation non technique se trouve sur la page [Comptes d'agence](agency-accounts.md#option-2-custom-payment-provider) ; cette page couvre la charge utile exacte du webhook et l'appel API que vous effectuez pour accorder les crédits par la suite.

Le webhook n'est qu'un des moyens par lesquels les rechargements automatiques sont payés. Si vous avez connecté [Stripe](agency-accounts.md#option-1-connect-stripe) ou [PayPal](agency-accounts.md#option-3-connect-paypal) en mode SaaS, la plateforme débite elle-même la carte enregistrée ou le compte PayPal du client et lui accorde les crédits ; vous n'avez donc rien à développer sur cette page. Ne poursuivez votre lecture que si vous souhaitez gérer le paiement vous-même.

***

## Aperçu du flux

1. Le solde de crédits d'un sous-compte tombe en dessous de son seuil de rechargement automatique.
2. La plateforme appelle votre **URL de webhook** avec les détails du sous-compte et le nombre de crédits dont il a besoin.
3. Votre serveur facture le client via le fournisseur que vous utilisez.
4. Votre serveur appelle l'**API d'octroi de crédits** pour ajouter des crédits à ce sous-compte.
5. Votre serveur répond `200` pour accuser réception du webhook.

***

## 1. Webhook : `agency_sub_account_auto_recharge`

Configurez l'URL du webhook en cliquant sur **SaaS Mode** dans la barre latérale principale, en choisissant **Use a Custom Payment Provider Instead** (ou, une fois configuré, en ouvrant la carte **Custom Payment Provider**), puis en remplissant le champ **Auto-Recharge Webhook**.

### Quand il est déclenché

Lorsqu'un solde de crédits de sous-compte tombe en dessous de son seuil de rechargement automatique configuré.

### Charge utile

```json
{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<sub-account-id>",
  "sub_account_email": "customer@example.com",
  "sub_account_name": "John Doe",
  "agency_id": "<agency-id>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}
```

| Champ | Description |
|---|---|
| `event` | Toujours `agency_sub_account_auto_recharge` pour ce webhook. |
| `sub_account_id` | L'identifiant unique du sous-compte qui a besoin de crédits. |
| `sub_account_email` | L'adresse e-mail du sous-compte. |
| `sub_account_name` | Le nom d'affichage du sous-compte. |
| `agency_id` | L'identifiant unique de votre compte d'agence. |
| `credits_requested` | Le nombre de crédits à accorder. Il s'agit de votre montant de rechargement configuré, mais si le solde est tombé plus bas sous le seuil que ce montant ne pourrait le couvrir, il est automatiquement augmenté pour atteindre ce qui est nécessaire pour ramener le solde au-dessus du seuil en une seule fois. Facturez toujours (et accordez) la valeur `credits_requested` de la charge utile — ne codez pas en dur votre montant de rechargement. |
| `current_balance` | Le solde de crédits du sous-compte au moment où le webhook a été envoyé. |
| `threshold` | Le seuil de solde qui a déclenché le rechargement. |
| `price_per_credit_cents` | Votre prix configuré par crédit, en centimes. |
| `price_per_credit_currency` | La devise du prix (par ex. `usd`). |
| `total_amount_cents` | Le montant total à facturer, en centimes (`credits_requested` × `price_per_credit_cents`). |
| `timestamp` | Quand le webhook a été envoyé (format ISO 8601). |
| `idempotency_key` | Une clé unique pour cette demande de rechargement spécifique. Utilisez-la pour éviter d'accorder des crédits deux fois si votre serveur reçoit le même webhook plus d'une fois. |

### Remarques importantes

- **Délai de refroidissement de 5 minutes** — Après une tentative de rechargement pour un sous-compte, la plateforme n'enverra pas d'autre webhook pour ce sous-compte pendant au moins 5 minutes, même si son solde baisse davantage. Cela évite les doubles facturations pendant le traitement.
- **Utilisez la clé d'idempotence** — Vérifiez toujours `idempotency_key` avant d'accorder des crédits. Si votre serveur a planté après avoir accordé des crédits mais avant de répondre, la plateforme peut renvoyer le webhook lors de la baisse de crédit suivante.
- **Les échecs sont sûrs et auto-réparateurs** — Si votre URL de webhook est inaccessible ou renvoie une erreur, aucun crédit n'est accordé. La plateforme continue de renvoyer le webhook (une fois par délai de refroidissement de 5 minutes) tant que le sous-compte reste en dessous du seuil — elle ne nécessite **pas** que le solde remonte au-dessus du seuil puis redescende. Une seule facturation manquée ne peut plus laisser un sous-compte sans rechargement permanent.
- **Définissez votre montant de rechargement au niveau ou au-dessus du seuil** — Votre montant de rechargement configuré doit être supérieur ou égal au seuil de rechargement automatique, afin qu'un rechargement restaure toujours le solde au-dessus du seuil. (Si vous devez un jour corriger un sous-compte qui a dérivé loin en dessous du seuil, la plateforme complète automatiquement le déficit total — voir `credits_requested` ci-dessus.)

***

## 2. API d'octroi de crédits

Une fois que votre serveur a traité le paiement, appelez ce point de terminaison pour ajouter les crédits au sous-compte.

### Requête

```http
POST https://api.dmchamp.com/v1/subaccounts/credits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "customer@example.com",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}
```

| Champ | Requis | Description |
|---|---|---|
| `email` | Oui | L'adresse e-mail du sous-compte (doit correspondre à un sous-compte existant sous votre agence). |
| `amount` | Oui | Le nombre de crédits à accorder. |
| `description` | Non | Une note décrivant pourquoi les crédits ont été ajoutés (affichée dans l'historique des transactions de crédit). |

**Authentification :** Envoyez votre clé API dans un en-tête de requête — soit `X-API-Key: YOUR_API_KEY`, soit `Authorization: Bearer YOUR_API_KEY`. Les en-têtes sont la méthode recommandée, car une clé dans l'URL finit dans l'historique du navigateur, les journaux du proxy et les journaux d'accès au serveur. Le paramètre de requête `?apiKey=YOUR_API_KEY` et un champ `apiKey` dans le corps JSON fonctionnent également toujours, afin que les anciennes intégrations continuent de fonctionner sans modification.

### Réponse

```json
{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}
```

::: tip
**Conseil :** Enregistrez le `idempotency_key` de la charge utile du webhook et vérifiez-le avant d'appeler ce point de terminaison. Cela évite d'accorder accidentellement des crédits deux fois si votre serveur reçoit le même webhook plus d'une fois.
:::


### Que deviennent les crédits accordés lors de la réinitialisation mensuelle

Cela dépend de la configuration du sous-compte :

- **Revente** (le sous-compte vous paie pour les crédits) : les crédits que vous accordez ici sont enregistrés comme des crédits achetés et sont **reportés** chaque mois. Tout ce que le sous-compte n'a pas dépensé reste sur le solde.
- **Allocation** (vous donnez au sous-compte une allocation mensuelle) : le solde est rechargé à hauteur de l'allocation mensuelle à la date de réinitialisation, donc tout montant non dépensé n'est pas reporté. C'est intentionnel : l'allocation est renouvelée chaque mois.

Si vous souhaitez que le solde restant d'un sous-compte soit ajouté à sa nouvelle allocation mensuelle au lieu de la remplacer, activez le report de crédits :

```
PUT https://api.dmchamp.com/v1/subaccounts/{subAccountUid}/limits
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "usageLimits": { "roll_over_to_next_month": true }
}
```

Si le sous-compte — ou le forfait auquel il est associé — dispose également d'un plafond de report ou d'une date d'expiration, la réinitialisation correspond au moment où ces règles s'appliquent : le crédit reporté est limité aux mois autorisés, et le crédit inutilisé au-delà de la période d'expiration est supprimé avant que le nouveau crédit ne soit ajouté. Les crédits accordés via ce point de terminaison, les rechargements automatiques et les rechargements effectués par le client sont des crédits ponctuels qui ne sont jamais supprimés. Voir [Limiter ce qui est reporté](sub-accounts.md#capping-what-rolls-over).

***

## Exemple de bout en bout

Un gestionnaire typique ressemble à ceci :

```pseudo
on POST /your-recharge-webhook:
  payload = request.body

  if seen(payload.idempotency_key):
    return 200  // already processed, ack and exit

  charge_result = your_payment_provider.charge(
    email = payload.sub_account_email,
    amount_cents = payload.total_amount_cents,
    currency = payload.price_per_credit_currency,
  )

  if not charge_result.ok:
    return 500  // platform will retry on next balance drop

  api.post("/v1/subaccounts/credits", {
    email = payload.sub_account_email,
    amount = payload.credits_requested,
    description = "Auto-recharge via " + your_provider_name,
  })

  mark_seen(payload.idempotency_key)
  return 200
```