Démarrage rapide

CajouPay permet à votre site d'encaisser des paiements PI-SPI, le système de paiement instantané de la BCEAO. Vous créez un paiement, vous redirigez votre client vers la page de paiement CajouPay, il saisit son alias (son numéro de téléphone, en général) et valide la demande dans l'application de sa banque ou de son portefeuille mobile. Le montant est crédité sur votre compte CajouPay, puis retiré vers votre compte bancaire.

Vous avez une boutique WooCommerce ?

Pas besoin de code : installez le plugin WooCommerce.

1. Récupérer une clé de test

Créez votre compte sur le tableau de bord CajouPay. Dans Développeurs, cliquez sur Renouveler la clé secrète : la clé sk_test_… s'affiche une seule fois, copiez-la.

En mode test, aucun argent ne circule : un simulateur joue le rôle de la banque du client (voir Mode test). Gardez la clé côté serveur, jamais dans le navigateur ni dans une application mobile.

2. Créer un paiement

Montants en francs CFA, entiers : 32500 signifie 32 500 FCFA.

curl

curl https://api.cajoupay.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-20481" \
  -d '{
    "amount": 32500,
    "reference": "CMD-20481",
    "description": "Commande Awa Mode",
    "return_url": "https://awa-mode.ci/commande/20481/merci",
    "cancel_url": "https://awa-mode.ci/panier",
    "metadata": { "order_id": "20481" }
  }'

PHP

$cajoupay = new \CajouPay\Client('sk_test_…');

$payment = $cajoupay->payments->create([
    'amount' => 32500,
    'reference' => 'CMD-20481',
    'description' => 'Commande Awa Mode',
    'return_url' => 'https://awa-mode.ci/commande/20481/merci',
    'cancel_url' => 'https://awa-mode.ci/panier',
    'metadata' => ['order_id' => '20481'],
], ['idempotency_key' => 'commande-20481']);

Node.js

const response = await fetch('https://api.cajoupay.com/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAJOUPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'commande-20481',
  },
  body: JSON.stringify({
    amount: 32500,
    reference: 'CMD-20481',
    description: 'Commande Awa Mode',
    return_url: 'https://awa-mode.ci/commande/20481/merci',
    cancel_url: 'https://awa-mode.ci/panier',
    metadata: { order_id: '20481' },
  }),
});
const payment = await response.json();

La réponse contient l'identifiant du paiement (pay_…), son statut (created) et surtout checkout_url, la page de paiement hébergée.

3. Rediriger le client

Envoyez le client vers checkout_url. Il choisit PI-SPI, saisit son alias et reçoit la demande dans son application. Une fois le paiement validé (ou s'il abandonne), il revient sur votre return_url (ou cancel_url).

Le retour du client ne prouve pas le paiement : il peut fermer la page avant. Confirmez toujours par le webhook ou en lisant le paiement (GET /v1/payments/{id}).

4. Être prévenu du paiement

Dans Développeurs, ajoutez l'adresse de votre serveur comme webhook et copiez son secret whsec_…. CajouPay y envoie un événement signé à chaque changement de statut : payment.succeeded quand l'argent est reçu. Voir Webhooks.

5. Tester puis passer en production

Rejouez les cas utiles avec les alias de test : paiement accepté, refusé, expiré, à la livraison. Quand votre compte est activé, renouvelez la clé de production sk_live_… dans le tableau de bord, remplacez la clé de test et le secret du webhook : le reste ne change pas.