Paiements

Un paiement naît de l’une de deux façons : via le flux de checkout (votre serveur crée une session, le client paie sur la page hébergée), ou directement par POST /api/v1/payments. Peu importe lequel, le calcul des frais et la confirmation par webhook se comportent exactement pareil ensuite. Seule la façon de démarrer diffère.

POST /api/v1/payments

Encaisse un paiement mobile money sans jamais passer par une session de checkout ni une page hébergée : votre serveur collecte le numéro et l’opérateur du client dans sa propre interface et appelle directement cet endpoint, en sandbox comme en live. Pour l’instant, seul le mobile money est pris en charge ici. La carte demande une étape de tokenisation côté client que cet endpoint ne gère pas encore.

En-têtes

Nom	Requis	Description
`Authorization`	oui	`Bearer mp_…`
`Content-Type`	oui	`application/json`
`Idempotency-Key`	recommandé	Évite les doublons, voir Idempotence

Corps

Champ	Requis	Type	Règles
`amount`	oui	entier	Unités mineures, au moins `1`
`currency`	oui	chaîne	Code ISO 4217 de 3 lettres
`country`	oui	chaîne	Pays ISO 3166-1 alpha-3, par exemple `CMR`
`provider`	oui	chaîne	Code opérateur, par exemple `MTN_MOMO_CMR`
`phone`	oui	chaîne	Numéro avec indicatif, sans `+`
`payer_name`	non	chaîne	255 caractères maximum
`payer_email`	non	chaîne	Adresse e-mail valide
`description`	non	chaîne	500 caractères maximum

curl https://mercy-pay.com/api/v1/payments \
  -H "Authorization: Bearer mp_live_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-9123" \
  -d '{
    "amount": 1000,
    "currency": "XAF",
    "country": "CMR",
    "provider": "MTN_MOMO_CMR",
    "phone": "237680000000",
    "description": "Commande 9123"
  }'

Réponse `201`

{
  "data": {
    "uuid": "5e0c8a7b-3d1f-4a2e-9c64-8b7f0d2e1a93",
    "checkout_session": null,
    "gross_amount": 1000,
    "psp_fee_amount": 20,
    "platform_fee_amount": 30,
    "net_amount_to_merchant": 950,
    "currency": "XAF",
    "payment_method": "mobile_money",
    "mobile_money_country": "CMR",
    "mobile_money_provider": "MTN_MOMO_CMR",
    "psp_reference": "3a7f1e2c-8b4d-4e9a-a6f0-1d5c9e7b2f48",
    "status": "pending",
    "failure_reason": null,
    "created_at": "2026-10-04T10:20:00+00:00"
  }
}

Le statut reste pending jusqu’à ce que le webhook payment.succeeded ou payment.failed tranche, exactement comme pour un paiement né d’une session de checkout. Voir Gérer les webhooks.

Un opérateur mobile money ne déplace que sa propre devise nationale. Si currency ne correspond pas à la devise du pays choisi (country), le montant est converti automatiquement avant l’encaissement. La réponse reflète alors le montant réellement prélevé, dans la devise de l’opérateur, pas celle envoyée dans la requête. Par exemple, une requête avec "amount": 1000, "currency": "XAF", "country": "RWA", "provider": "MTN_MOMO_RWA" encaisse réellement en RWF : la réponse renvoie "currency": "RWF" et gross_amount dans cette devise. Si aucun taux n’est disponible pour la devise de l’opérateur, la requête échoue en 422.

Erreurs

Code	Cause
`403`	Clé live et KYC non approuvé, ou marchand suspendu
`422`	Pays/opérateur invalide, numéro manquant ou invalide, devise non convertible vers celle de l’opérateur, ou paiement refusé (voir `failure_reason`)

GET /api/v1/payments

Liste vos paiements, du plus récent au plus ancien.

Paramètre	Description
`status`	`pending`, `processing`, `succeeded`, `failed`, `canceled`, `expired`, `refunded`, `disputed`
`from`, `to`	Dates `AAAA-MM-JJ`, bornes incluses
`per_page`	20 par défaut, 100 au maximum

curl "https://mercy-pay.com/api/v1/payments?status=succeeded&per_page=5" \
  -H "Authorization: Bearer mp_sandbox_XXXXXXXXXXXXXXXX"

GET /api/v1/payments/

Renvoie un paiement, qu’il vienne d’une session de checkout ou d’une charge directe.

Réponse

{
  "data": {
    "uuid": "5e0c8a7b-3d1f-4a2e-9c64-8b7f0d2e1a93",
    "checkout_session": "01J9Z3V8QK4M2XW7R6TB5N0HYD",
    "gross_amount": 15000,
    "psp_fee_amount": 300,
    "platform_fee_amount": 450,
    "net_amount_to_merchant": 14250,
    "currency": "XAF",
    "payment_method": "mobile_money",
    "mobile_money_country": "CMR",
    "mobile_money_provider": "MTN_MOMO_CMR",
    "psp_reference": "3a7f1e2c-8b4d-4e9a-a6f0-1d5c9e7b2f48",
    "status": "succeeded",
    "failure_reason": null,
    "created_at": "2026-10-03T10:20:00+00:00"
  }
}

Champ	Description
`checkout_session`	Référence de la session de checkout à l’origine du paiement, `null` pour une charge directe
`gross_amount`	Montant payé par le client
`psp_fee_amount`, `platform_fee_amount`	Décomposition informative de la commission
`net_amount_to_merchant`	Montant crédité à votre solde
`mobile_money_country`, `mobile_money_provider`	Pays et opérateur. `null` pour une carte.
`failure_reason`	Raison de l’échec si `status` est `failed`, sinon `null`

Voir Paiements pour les statuts.

Erreurs

Code	Cause
`404`	Paiement inconnu, ou appartenant à un autre marchand

Endpoints

Ressources

POST /api/v1/payments

En-têtes

Corps

Réponse `201`

Erreurs

GET /api/v1/payments

GET /api/v1/payments/

Réponse

Erreurs

​POST /api/v1/payments

​En-têtes

​Corps

​Réponse 201

​Erreurs

​GET /api/v1/payments

​GET /api/v1/payments/

​Réponse

​Erreurs

POST /api/v1/payments

En-têtes

Corps

Réponse `201`

Erreurs

GET /api/v1/payments

GET /api/v1/payments/

Réponse

Erreurs