Accepter un paiement récurrent

Ce guide couvre la mise en place d’un abonnement, du plan jusqu’au premier prélèvement. Voir Abonnements pour le fonctionnement général, notamment la différence de comportement entre carte et mobile money.

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.

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"
  }'

$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);

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();

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.

Inscrivez votre client, avec son moyen de paiement

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"
  }'

$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);

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();

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.

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.

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.

Annulez quand nécessaire

curl -X POST https://mercy-pay.com/api/v1/subscriptions/sub_2f8a6c1e4b3d4a5e8f6c2d9b1a7e3c48/cancel \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX"

$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);

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();

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

Démarrage

Paiements

Liens de paiement

Abonnements

Soldes et retraits

Développeurs

Accepter un paiement récurrent

Erreurs fréquentes