Intégrez la caisse C-Pay à votre site ou votre application

Démarrage rapide

Périmètre de lancement : les six pays de la CEMAC et la RD Congo. Moyens prévus : cartes bancaires, opérateurs de monnaie mobile et GIMAC. Les fonctions sont disponibles selon le pays et le service activés ; la connexion GIMAC est en cours d’intégration. La détection d’un numéro ne garantit pas la disponibilité d’un paiement.

Trois étapes séparent votre compte de votre premier lien de paiement. Un compte de niveau 0 suffit pour intégrer ; la vérification KYB n'est nécessaire que pour relever vos limites.

1. Créez un compte marchand

   Sur merchant.c-pay.global/register. Le portail marchand est aussi l'endroit où vous suivez les paiements reçus par l'API.

2. Créez une clé API dans le portail

   Portail marchand → Clés API → nouvelle clé avec les permissions voulues (pay_links, transactions). La clé et son secret ne sont affichés qu'une fois : stockez-les côté serveur, jamais dans un navigateur ou une application mobile.

3. Créez votre premier lien de paiement

   Trois appels cURL ci-dessous : vérifier la clé, créer le lien, retrouver le paiement dans vos transactions.

Votre premier lien de paiement en trois appels

# 1. Vérifier la clé : la liste (vide ou non) de vos transactions répond 200
curl https://api.c-pay.global/api/v1/merchant/public/transactions?limit=1 \
  -H "X-API-Key: $CPAY_API_KEY" \
  -H "X-API-Secret: $CPAY_API_SECRET"

# 2. Créer un lien de paiement de 25 000 XAF valable 48 h
curl -X POST https://api.c-pay.global/api/v1/merchant/public/pay-links \
  -H "X-API-Key: $CPAY_API_KEY" \
  -H "X-API-Secret: $CPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25000, "currency": "XAF", "description": "Facture INV-001", "expiresIn": 48 }'
# → 201 { "short_url": "https://pay.c-pay.global/AB12CD", "expires_at": "…", … }
#   Envoyez short_url à votre client (SMS, WhatsApp, e-mail) ou affichez-le en QR.

# 3. Retrouver le paiement une fois le client passé par la page
curl "https://api.c-pay.global/api/v1/merchant/public/transactions?status=authorized&limit=5" \
  -H "X-API-Key: $CPAY_API_KEY" \
  -H "X-API-Secret: $CPAY_API_SECRET"

Pour être prévenu sans interroger l'API, configurez un webhook : C-Pay appelle votre serveur à chaque paiement confirmé ou échoué.

Authentification et conventions

Les endpoints /merchant/public/* s'authentifient par clé API. Les endpoints de l'API Caisse utilisent la session du marchand (jeton Bearer). Toutes les requêtes et réponses sont en JSON.

Base URL

https://api.c-pay.global/api/v1

Montants

Les exemples du lancement utilisent des montants entiers en XAF ou en CDF. Aucune conversion de change : la devise du client doit être celle du marchand.

Erreurs

Corps { "error": "message lisible", "code": "CODE_STABLE", "details?": … }. Codez sur code, pas sur error. Liste dans Codes d'erreur.

Permissions

Chaque clé porte ses permissions (pay_links, transactions, collect, disburse). Permission manquante : 403.

Limites de débit

Les points d'entrée publics sont limités en débit ; 429 avec les en-têtes RateLimit-* standard. POST /detect/phone : 30 requêtes par minute et par adresse.

Sécurité

N'appelez l'API que depuis votre serveur. Une clé exposée dans un navigateur ou une application mobile doit être révoquée immédiatement dans le portail.

Référence des endpoints publics

Seuls les endpoints réellement en production figurent ici. La référence Swagger fait foi en cas d'écart.

curl -X POST https://api.c-pay.global/api/v1/merchant/public/pay-links \
  -H "X-API-Key: $CPAY_API_KEY" \
  -H "X-API-Secret: $CPAY_API_SECRET" \
  -H "Idempotency-Key: 0b4e8d2a-11aa-4f4b-8c3e-9d2f1e0a5b6c" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25000, "currency": "XAF", "description": "Facture INV-001", "expiresIn": 48 }'

// Node.js 18+ — côté serveur uniquement
const res = await fetch('https://api.c-pay.global/api/v1/merchant/public/pay-links', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.CPAY_API_KEY,
    'X-API-Secret': process.env.CPAY_API_SECRET,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 25000, currency: 'XAF', description: 'Facture INV-001', expiresIn: 48 })
});
const link = await res.json();
if (!res.ok) throw new Error(`${link.code}: ${link.error}`);
console.log(link.short_url); // https://pay.c-pay.global/AB12CD

<?php
// PHP 8+, cURL natif
$ch = curl_init('https://api.c-pay.global/api/v1/merchant/public/pay-links');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('CPAY_API_KEY'),
        'X-API-Secret: ' . getenv('CPAY_API_SECRET'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 25000, 'currency' => 'XAF', 'description' => 'Facture INV-001', 'expiresIn' => 48,
    ]),
]);
$link = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException(($link['code'] ?? $status) . ': ' . ($link['error'] ?? 'erreur'));
echo $link['short_url'];

# Python 3.9+, bibliothèque standard
import json, os, uuid, urllib.request

req = urllib.request.Request(
    "https://api.c-pay.global/api/v1/merchant/public/pay-links",
    data=json.dumps({"amount": 25000, "currency": "XAF", "description": "Facture INV-001", "expiresIn": 48}).encode(),
    headers={
        "X-API-Key": os.environ["CPAY_API_KEY"],
        "X-API-Secret": os.environ["CPAY_API_SECRET"],
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=15) as r:
    link = json.load(r)
print(link["short_url"])

{
  "success": true,
  "pay_link_id": "7f1c2b9e-3d44-4c0a-9a7e-2a1b5c6d7e8f",
  "short_id": "AB12CD",
  "short_url": "https://pay.c-pay.global/AB12CD",
  "amount": 25000,
  "currency": "XAF",
  "expires_at": "2026-10-18T10:00:00.000Z"
}

curl "https://api.c-pay.global/api/v1/merchant/public/transactions?status=authorized&page=1&limit=20" \
  -H "X-API-Key: $CPAY_API_KEY" \
  -H "X-API-Secret: $CPAY_API_SECRET"

const url = new URL('https://api.c-pay.global/api/v1/merchant/public/transactions');
url.searchParams.set('status', 'authorized');
url.searchParams.set('limit', '20');
const res = await fetch(url, {
  headers: { 'X-API-Key': process.env.CPAY_API_KEY, 'X-API-Secret': process.env.CPAY_API_SECRET }
});
const { data, total } = await res.json();
console.log(total, data[0]?.reference);

<?php
$ch = curl_init('https://api.c-pay.global/api/v1/merchant/public/transactions?' . http_build_query([
    'status' => 'authorized', 'limit' => 20,
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('CPAY_API_KEY'),
        'X-API-Secret: ' . getenv('CPAY_API_SECRET'),
    ],
]);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $page['total'];

import json, os, urllib.parse, urllib.request

qs = urllib.parse.urlencode({"status": "authorized", "limit": 20})
req = urllib.request.Request(
    "https://api.c-pay.global/api/v1/merchant/public/transactions?" + qs,
    headers={"X-API-Key": os.environ["CPAY_API_KEY"], "X-API-Secret": os.environ["CPAY_API_SECRET"]},
)
with urllib.request.urlopen(req, timeout=15) as r:
    page = json.load(r)
print(page["total"])

{
  "data": [
    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "collect",
      "amount": 25000,
      "currency": "XAF",
      "status": "authorized",
      "payment_method": "mobile_money",
      "auth_code": "FT123456",
      "reference": "INV-001",
      "initiated_at": "2026-10-16T09:12:33.120Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

curl -X POST https://api.c-pay.global/api/v1/detect/phone \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+237670123456" }'

const res = await fetch('https://api.c-pay.global/api/v1/detect/phone', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ phone: '+237670123456' })
});
const d = await res.json();
if (d.success) console.log(d.countryName, d.currency, d.brand); // Cameroun XAF MTN Mobile Money

<?php
$ch = curl_init('https://api.c-pay.global/api/v1/detect/phone');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['phone' => '+237670123456']),
]);
$d = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($d['success']) echo $d['countryName'], ' ', $d['currency'], ' ', $d['brand'];

import json, urllib.request

req = urllib.request.Request(
    "https://api.c-pay.global/api/v1/detect/phone",
    data=json.dumps({"phone": "+237670123456"}).encode(),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=10) as r:
    d = json.load(r)
if d["success"]:
    print(d["countryName"], d["currency"], d["brand"])

{
  "success": true,
  "phone": "+237670123456",
  "country": "CM",
  "countryName": "Cameroun",
  "currency": "XAF",
  "region": "CEMAC",
  "operator": "mtn_momo",
  "brand": "MTN Mobile Money",
  "alternatives": [ { "operator": "express_union", "brand": "Express Union" } ]
}

API Caisse session marchand

Ces endpoints portent les opérations de caisse du portail marchand et de l'application Android : encaisser, retirer, transférer, suivre. Ils sont authentifiés par la session du marchand (Authorization: Bearer <access> obtenu via POST /merchant/auth/login, 15 minutes, renouvelé par /merchant/auth/refresh), pas par clé API. Ils conviennent à vos propres outils de caisse ; pour une intégration serveur, préférez les endpoints publics ci-dessus. Toute requête qui crée un mouvement exige Idempotency-Key.

Confirmation forte : l'objet confirm

Les retraits, les transferts wallet_to_bank et l'enregistrement du wallet exigent un objet confirm dans le corps. Son contenu dépend de la configuration du compte :

Objet absent ou invalide : 428 STEP_UP_REQUIRED { "methods": ["totp"] } ou ["password"], qui indique la méthode à présenter. Cinq échecs en 15 minutes : 429. Un ordre bank_to_wallet n'exige pas de confirmation : aucun fonds ne quitte le compte.

# Retrait de 50 000 vers le wallet enregistré (compte avec 2FA)
curl -X POST https://api.c-pay.global/api/v1/merchant/cash/withdraw \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 2c1f6a1e-5e0b-4f7c-9a3d-8b2e4c6d1f0a" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000, "description": "Caisse du soir", "confirm": { "code": "123456" } }'

# Transfert wallet -> banque (compte sans 2FA)
curl -X POST https://api.c-pay.global/api/v1/merchant/cash/transfers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 9d7e5c3a-1b2f-4e6d-8a0c-3f5b7d9e1a2c" \
  -H "Content-Type: application/json" \
  -d '{ "direction": "wallet_to_bank", "accountId": "<account_id>", "amount": 200000, "confirm": { "password": "…" } }'

Webhooks sortants

Déclarez une URL https:// dans le portail marchand (rubrique Webhooks) ; le secret de signature est affiché une seule fois à la création. À chaque changement de statut, C-Pay envoie un POST JSON signé en HMAC-SHA256. Les adresses privées ou non HTTPS sont refusées, les redirections ne sont pas suivies, le délai maximal est de 10 secondes et une réponse 5xx ou une erreur réseau déclenche jusqu'à 3 nouvelles tentatives (5 s puis 10 s).

En-têtes envoyés

Content-Type:      application/json
User-Agent:        CPay-Webhooks/1.0
X-CPay-Event:      payment.completed
X-CPay-Signature:  sha256=3f1a…c9        ← à vérifier
X-CPay-Timestamp:  2026-10-16T09:12:33.120Z   (informatif, non signé)
X-CPlus-Event:     payment.completed       (transition, sera retiré)
X-CPlus-Signature: sha256=3f1a…c9        (transition, sera retiré)

Les en-têtes X-CPlus-* sont conservés provisoirement pour les consommateurs existants et seront retirés au plus tôt 90 jours après annonce sur cette page. Nouvelles intégrations : n'utilisez que X-CPay-Signature.

Événements et corps

Événements du webhook marchand : payment.completed, payment.failed, webhook.test (même forme, txnId préfixé test-, envoyé par le bouton « Tester » du portail).

{
  "event": "payment.completed",
  "txnId": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "INV-001",
  "amount": 25000,
  "currency": "XAF",
  "status": "authorized",
  "method": "mobile_money",
  "authCode": "FT123456",
  "timestamp": "2026-10-16T09:12:33.120Z"
}

Vérifier la signature

signature = "sha256=" + hex(HMAC-SHA256(secret, corps brut)). Calculez sur le corps exactement tel qu'il est reçu (octets, pas une re-sérialisation JSON), comparez en temps constant, répondez 2xx rapidement puis traitez en asynchrone. Un même événement peut être livré plusieurs fois : dédupliquez sur txnId.

const crypto = require('crypto');
app.post('/cpay/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const given = String(req.get('X-CPay-Signature') || '').replace(/^sha256=/, '');
  const expected = crypto.createHmac('sha256', process.env.CPAY_WEBHOOK_SECRET).update(req.body).digest('hex');
  if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body);   // { event, txnId, reference, amount, currency, status, method, authCode, timestamp }
  res.status(200).end();                // puis traitement asynchrone, idempotent sur event.txnId
});

<?php
$raw = file_get_contents('php://input');
$given = preg_replace('/^sha256=/', '', $_SERVER['HTTP_X_CPAY_SIGNATURE'] ?? '');
$expected = hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $given)) { http_response_code(401); exit; }
$event = json_decode($raw, true);
http_response_code(200);
// puis traitement asynchrone, idempotent sur $event['txnId']

import hmac, hashlib

expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
given = request.headers.get("X-CPay-Signature", "").removeprefix("sha256=")
if not hmac.compare_digest(expected, given):
    abort(401)
event = json.loads(raw_body)
# répondre 200, puis traiter en asynchrone, idempotent sur event["txnId"]

SDK & plugin

Les SDK encapsulent l'authentification, l'idempotence et la vérification des webhooks. Ils sont facultatifs : l'API s'utilise avec n'importe quel client HTTP.

npm install @c-pay/sdk

const { CPayClient } = require('@c-pay/sdk');
const cpay = new CPayClient({ apiKey: process.env.CPAY_API_KEY, currency: 'XAF' });
const link = await cpay.collection.payLink({ amount: 25000, description: 'Facture INV-001' });
console.log(link.short_url);

composer require calculus-plus/cpay-sdk

use CPay\CPayClient;
$cpay = new CPayClient(getenv('CPAY_API_KEY'), ['currency' => 'XAF']);
$link = $cpay->createPayLink(25000, ['description' => 'Facture INV-001']);
echo $link['short_url'];

Les SDK 1.1.0 envoient X-API-Key mais pas encore X-API-Secret : utilisez-les avec une clé d'ancienne génération (sans secret) ou appelez l'API directement comme ci-dessus. Les sources sont remises par developers@c-pay.global si votre gestionnaire de paquets ne trouve pas encore le paquet.

Archives à télécharger

Version 2.7.0. Vérifiez l'empreinte SHA-256 après téléchargement (sha256sum fichier.zip).

1. WordPress → Extensions → Ajouter → Téléverser l'archive
2. Activer, puis WooCommerce → Réglages → Paiements → C-Pay
3. Renseigner la clé API et le secret (portail marchand → Clés API)
4. Déclarer l'URL de webhook affichée par l'extension dans le portail marchand (rubrique Webhooks)

// Initialisation — identifiants fournis par votre serveur
CPay.init(context, CPayConfig(apiKey = cleFournieParVotreServeur, env = CPayEnv.PRODUCTION))

// Encaissement : montant + numéro, l'opérateur est détecté
CPay.collect(activity, amount = 5000.0, customerPhone = "+237670123456", reference = "CMD-001",
    onSuccess = { txn -> confirmerCommande(txn.txnId) },
    onError   = { err -> afficherErreur(err.message) })

Sandbox

Codes d'erreur

Toute erreur renvoie { "error", "code", "details?" }. Les codes ci-dessous sont stables ; le message error peut changer.