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

# Accepter un paiement récurrent

> Créez un plan, inscrivez un client, laissez Mercy Pay facturer chaque cycle.

Ce guide couvre la mise en place d'un abonnement, du plan jusqu'au premier prélèvement. Voir [Abonnements](https://docs.mercy-pay.com/subscriptions/overview.md) pour le fonctionnement général, notamment la différence de comportement entre carte et mobile money.

**1. Créez un plan**

Un plan fixe le prix, la devise et la fréquence, pas le moyen de paiement, qui se choisit par client à l'étape suivante. Un même plan est donc réutilisable pour vos clients carte comme pour vos clients mobile money.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://mercy-pay.com/api/v1/plans \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Abonnement Pro",
    "amount": 5000,
    "currency": "XAF",
    "interval": "monthly"
  }'
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ch = curl_init('https://mercy-pay.com/api/v1/plans');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'Abonnement Pro',
    'amount' => 5000,
    'currency' => 'XAF',
    'interval' => 'monthly',
]));

$response = curl_exec($ch);
curl_close($ch);
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://mercy-pay.com/api/v1/plans', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Abonnement Pro',
    amount: 5000,
    currency: 'XAF',
    interval: 'monthly',
  }),
});

const data = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.post(
    'https://mercy-pay.com/api/v1/plans',
    headers={'Authorization': 'Bearer mp_live_XXXXXXXXXXXXXXXX'},
    json={
        'name': 'Abonnement Pro',
        'amount': 5000,
        'currency': 'XAF',
        'interval': 'monthly',
    },
)

data = response.json()
```

Vous pouvez aussi créer un plan depuis votre tableau de bord, section Abonnements, sans passer par l'API.

**2. Inscrivez votre client, avec son moyen de paiement**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://mercy-pay.com/api/v1/subscriptions \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "plan_9b1e4c2a6d3f4a5e8f6c2d9b1a7e3c48",
    "payment_method": "card",
    "customer_name": "Ada Lovelace",
    "customer_email": "ada@example.com"
  }'
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ch = curl_init('https://mercy-pay.com/api/v1/subscriptions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'plan' => 'plan_9b1e4c2a6d3f4a5e8f6c2d9b1a7e3c48',
    'payment_method' => 'card',
    'customer_name' => 'Ada Lovelace',
    'customer_email' => 'ada@example.com',
]));

$response = curl_exec($ch);
curl_close($ch);
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://mercy-pay.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mp_live_XXXXXXXXXXXXXXXX',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    plan: 'plan_9b1e4c2a6d3f4a5e8f6c2d9b1a7e3c48',
    payment_method: 'card',
    customer_name: 'Ada Lovelace',
    customer_email: 'ada@example.com',
  }),
});

const data = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.post(
    'https://mercy-pay.com/api/v1/subscriptions',
    headers={'Authorization': 'Bearer mp_live_XXXXXXXXXXXXXXXX'},
    json={
        'plan': 'plan_9b1e4c2a6d3f4a5e8f6c2d9b1a7e3c48',
        'payment_method': 'card',
        'customer_name': 'Ada Lovelace',
        'customer_email': 'ada@example.com',
    },
)

data = response.json()
```

`customer_email` est obligatoire : votre client y reçoit ses reçus, ses rappels et l'accès à son espace client. `payment_method` est facultatif : sans lui, le client choisit sur la page de paiement. Avec `payment_method: "mobile_money"` et `customer_phone`, `customer_country` et `customer_provider` (par exemple `MTN_MOMO_CMR`), la première demande part tout de suite sur ce téléphone.

**3. Faites payer votre client pour activer**

L'abonnement démarre `incomplete`. Redirigez votre client vers `next_action.redirect_url` (`https://mercy-pay.com/abonnements/{uuid}/payer`), une page hébergée par Mercy Pay, sans rien à intégrer de votre côté. Il y paie le premier cycle par carte ou mobile money, ou enregistre son moyen de paiement si le plan a un essai.

Donnez l'accès à votre service quand vous recevez `subscription.created` : l'abonnement est alors `active` ou `trialing`. Sans paiement sous 48 heures, l'inscription est annulée.

**4. Laissez Mercy Pay facturer chaque cycle**

Rien à planifier. À chaque échéance, Mercy Pay essaie les moyens enregistrés du client dans l'ordre : il débite la carte, ou envoie une demande de paiement sur son téléphone 2 jours avant l'échéance. Votre client reçoit un rappel 3 jours avant, puis son reçu. En cas d'échec, Mercy Pay relance à J+1, J+3 et J+7, puis annule. Écoutez `invoice.paid` et `invoice.payment_failed` pour suivre chaque facture, et `subscription.unpaid` pour couper l'accès d'un client mobile money qui n'a pas payé à l'échéance. Voir [Gérer les webhooks](https://docs.mercy-pay.com/developers/webhooks/handle.md).

**5. Annulez quand nécessaire**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://mercy-pay.com/api/v1/subscriptions/sub_2f8a6c1e4b3d4a5e8f6c2d9b1a7e3c48/cancel \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX"
```

```php PHP theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ch = curl_init('https://mercy-pay.com/api/v1/subscriptions/sub_2f8a6c1e4b3d4a5e8f6c2d9b1a7e3c48/cancel');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX',
]);

$response = curl_exec($ch);
curl_close($ch);
```

```js JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
  'https://mercy-pay.com/api/v1/subscriptions/sub_2f8a6c1e4b3d4a5e8f6c2d9b1a7e3c48/cancel',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer mp_live_XXXXXXXXXXXXXXXX',
    },
  },
);

const data = await response.json();
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests

response = requests.post(
    'https://mercy-pay.com/api/v1/subscriptions/sub_2f8a6c1e4b3d4a5e8f6c2d9b1a7e3c48/cancel',
    headers={'Authorization': 'Bearer mp_live_XXXXXXXXXXXXXXXX'},
)

data = response.json()
```

Immédiat par défaut. Passez `{"at_period_end": true}` pour laisser l'abonnement courir jusqu'à la fin du cycle payé.

## Erreurs fréquentes

| Message | Cause |
| - | - |
| Erreur de validation sur `customer_email` | Adresse e-mail absente : elle est obligatoire pour tout abonnement |
| Erreur de validation sur `customer_provider` | `payment_method: "mobile_money"` sans opérateur valide pour le pays, ou numéro invalide |
| Erreur de validation sur `plan` | Plan inconnu, archivé, ou appartenant à un autre marchand |


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