API partenaires

Deux adresses de base. Un seul numéro de version, celui de la plateforme.

production   https://superapp.creditruralgn.com/api/v1/partner
sandbox      https://staging.superapp.creditruralgn.com/api/v1/partner

L'environnement est déterminé par votre clé, jamais par un paramètre : une clé de sandbox ne peut pas demander à être traitée en production.

Chaque opération d'écriture exige un en-tête Idempotency-Key. Rejouer la même clé rend le même résultat — succès comme échec — au lieu de créer une seconde opération. C'est votre protection quand le réseau coupe après l'envoi : sans elle, vous ne pouvez pas distinguer « rien n'est parti » de « c'est passé mais je ne l'ai pas su ».

Votre reference doit être unique chez vous : c'est votre clé de rapprochement, et la réutiliser renvoie 409.

Nous ne délivrons pas de jeton porteur. Un jeton prouve l'identité, pas l'intégrité : il laisse modifier le montant en vol et rejouer la requête. Chaque appel est donc signé.

La chaîne à signer, en cinq parties séparées par un point :

timestamp . nonce . MÉTHODE . chemin . sha256(corps)

signature = hex( HMAC-SHA256( secret, chaîne ) )

Le chemin est celui de la requête, paramètres compris. Le sha256 porte sur le corps brut, octet pour octet : ne le re-sérialisez pas avant de signer, l'ordre des clés JSON changerait la signature. Un corps vide se signe comme la chaîne vide.

// Node.js
const crypto = require("crypto");

function signer({ secret, method, path, body }) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = crypto.randomBytes(16).toString("hex");
  const empreinte = crypto.createHash("sha256").update(body ?? "").digest("hex");
  const chaine = [timestamp, nonce, method.toUpperCase(), path, empreinte].join(".");
  return {
    "X-CRG-Key-Id": process.env.CRG_KEY_ID,
    "X-CRG-Timestamp": timestamp,
    "X-CRG-Nonce": nonce,
    "X-CRG-Signature": crypto.createHmac("sha256", secret).update(chaine).digest("hex"),
  };
}

Votre clé de sandbox commence par pk_sandbox_. Rien n'y bouge : aucun portefeuille réel, aucun float, aucune écriture comptable. Le fichier client n'y est jamais lu — seuls les numéros ci-dessous existent.

Servez-vous en pour coder les chemins d'échec. C'est leur raison d'être : une intégration qui ne connaît que le chemin heureux découvre les autres en production.

Le solde de float en sandbox est constant et généreux : le refus pour fonds insuffisants se provoque par le numéro 622000002, pas en épuisant un compteur.

Vous versez depuis un float préfinancé chez CRG. Chaque versement le débite ; un float insuffisant refuse le versement, il ne le met pas en attente. Surveillez votre solde.

POST /api/v1/partner/payouts
Idempotency-Key: 7f3a9c12-...

{
  "reference": "ACME-2026-000418",
  "phone": "622451230",
  "amountCentimes": 5000000,
  "narration": "Transfert depuis Acme Pay"
}

→ 201
{
  "id": "…", "reference": "ACME-2026-000418",
  "phone": "622451230", "amountCentimes": 5000000,
  "status": "succeeded", "failureCode": null,
  "environment": "live", "createdAt": "2026-10-16T12:00:00.000Z"
}

Pour un achat en ligne ou une facture. Vous créez une demande ; elle n'engage rien. Seul le client la transforme en paiement, sur une page servie par CRG ou dans son application, avec son code PIN.

POST /api/v1/partner/charges
Idempotency-Key: 2b84e0f1-...

{
  "reference": "SHOP-4471",
  "phone": "622451230",
  "amountCentimes": 2500000,
  "narration": "Commande 4471 — 2 articles"
}

→ 201
{
  "status": "pending",
  "authorizationUrl": "https://superapp.creditruralgn.com/pay/…",
  "expiresAt": "2026-10-16T12:15:00.000Z"
}

Les états possibles : pending, succeeded, declined si le client refuse, expired au bout des 15 minutes, canceled si vous annulez, failed avec un code si le débit n'a pas abouti.

Le narration est obligatoire : un client à qui l'on demande d'autoriser un débit doit savoir pour quoi.

Pour un abonnement ou une facture récurrente. Le client consent une fois ; vous prélevez ensuite sans lui redemander son PIN.

Un mandat n'est pas un blanc-seing. Trois bornes vous sont opposables, et une quatrième appartient au client :

Donnez-nous une adresse HTTPS et nous vous notifions. Vous recevez un secret de signature, distinct de celui de vos appels : les deux voyagent dans des sens opposés et se révoquent indépendamment.

// Vérification — Node.js / Express avec le corps BRUT
const attendue = crypto
  .createHmac("sha256", process.env.CRG_WEBHOOK_SECRET)
  .update(`${req.header("X-CRG-Timestamp")}.${rawBody}`)
  .digest("hex");

const fournie = req.header("X-CRG-Signature");
const ok =
  attendue.length === fournie.length &&
  crypto.timingSafeEqual(Buffer.from(attendue), Buffer.from(fournie));

if (!ok) return res.sendStatus(401);

Vérifiez aussi que l'horodatage est récent : sans cela, un rappel capté serait rejouable indéfiniment contre votre serveur.

Les événements que nous émettons :

payout.succeeded          payout.failed
charge.succeeded          charge.failed
charge.declined           charge.expired
mandate.activated         mandate.revoked
mandate.debit.succeeded   mandate.debit.failed

Les rappels partent aussi en sandbox : éprouvez-les là avant la production.

Les refus métier ne sont pas des erreurs HTTP. Ils arrivent avec status: "failed" et un code stable :