Aller au contenu
AfriContext
Publier un contexte

CinetPay

CinetPay - Guichet de paiement

Initialise un paiement CinetPay, redirige vers payment_url et confirme par /payment/check après la notification.

Vérifié sur la doc officielle • Vérifié sur la doc officielle • 06.10.26API v2

Authentification

  • Pas de header d'authentification : apikey et site_id sont envoyés dans le corps JSON.
  • Les lire depuis l'environnement côté serveur uniquement.

Endpoints

  • POST https://api-checkout.cinetpay.com/v2/payment
    • Requis : apikey, site_id, transaction_id, amount, currency, description, notify_url, return_url, channels.
    • Réponse : code: "201", data.payment_token, data.payment_url.
  • POST https://api-checkout.cinetpay.com/v2/payment/check avec apikey, site_id, transaction_id.
    • data.status : ACCEPTED, REFUSED, PENDING.

Erreurs

  • Le champ code est une chaîne : "201" succès, "600" erreur de paramètre, "609" authentification.
  • Le statut HTTP peut être 200 même en cas d'erreur : lire code.

Webhooks

  • CinetPay appelle notify_url en POST formulaire avec cpm_trans_id et cpm_site_id.
  • Header x-token : HMAC de contrôle, à vérifier avec la clé secrète du compte.
  • Toujours confirmer avec /v2/payment/check avant de livrer.

Idempotence et limites

  • transaction_id unique par paiement.

Pièges courants

Ce que les LLMs inventent le plus souvent pour CinetPay.

  • amount doit être un multiple de 5 pour le XOF.
  • channels vaut ALL, MOBILE_MONEY, CREDIT_CARD ou WALLET.
  • Le succès est code === "201", pas res.ok.

Exemple minimal

1export async function initCinetPay(transactionId: string, amount: number): Promise<string> {2  const res = await fetch("https://api-checkout.cinetpay.com/v2/payment", {3    method: "POST",4    headers: { "Content-Type": "application/json" },5    body: JSON.stringify({6      apikey: process.env.CINETPAY_API_KEY,7      site_id: process.env.CINETPAY_SITE_ID,8      transaction_id: transactionId,9      amount: Math.ceil(amount / 5) * 5,10      currency: "XOF",11      description: "Commande " + transactionId,12      notify_url: process.env.APP_URL + "/api/webhooks/cinetpay",13      return_url: process.env.APP_URL + "/paiement/retour",14      channels: "ALL",15    }),16  });17  const json = (await res.json()) as { code: string; data: { payment_url: string } };18  if (json.code !== "201") throw new Error("CinetPay " + json.code);19  return json.data.payment_url;20}

Variables d'environnement

  • CINETPAY_API_KEY
  • CINETPAY_SITE_ID
  • CINETPAY_SECRET_KEY
  • APP_URL