Règle de sécurité impérative : Aucune clé secrète côté client
Les clés API marchandes (cp_live_..., cp_test_..., sec_live_..., sec_test_...) et secrets webhook (whsec_...) possèdent des privilèges financiers et ne doivent JAMAIS être incluses dans des applications front-end ou mobiles (React Web, React Native, Expo, Flutter).
La création des devis et sessions de paiement doit toujours s'effectuer via votre propre backend sécurisé. Les composants front-end et mobiles consomment exclusivement des jetons éphémères de checkout hébergé ou des QR codes publics.
Qualifié Localement · Serveur
v1.0.0
1. PHP SDK
SDK backend officiel pour PHP 8.1+, Laravel et Symfony. Devis, paiements, sessions checkout, QR statique/dynamique, protection anti-SSRF avec épinglage IP CURLOPT_RESOLVE et webhooks HMAC-SHA256 (52/52 tests validés).
packages/sdk-php · chadpay/chadpay-php
Dépôt path Composer local ou archive vérifiée (non publié sur Packagist)
Voir le guide PHP complet →
Qualifié Localement · Serveur
v1.0.0
2. Node.js / TypeScript Core
SDK TypeScript ESM zéro dépendance pour Node.js 18+, AdonisJS, NestJS, Express et Next.js Server. Validation DNS anti-SSRF complète, retries idempotents et WebhooksService (48/48 tests validés).
npm install ./packages/sdk
Paquet local ./packages/sdk ou archive .tgz (non publié sur npm public)
Voir le guide TypeScript complet →
Qualifié Localement · Client Web
v0.2.0
3. React Web Components
Hook frontal useChadPayCheckout pour React 18 & 19. Modes redirection et fenêtre modale avec validation stricte de l'origine postMessage et rejet automatique des clés secrètes (4/4 tests validés).
npm install ./packages/react
Consomme exclusivement un checkoutToken public (non publié sur npm public)
Voir le guide React complet →
Qualifié Localement · Mobile
v0.2.0
4. React Native & Expo
Helper mobile useChadPayMobile pour React Native et Expo. Construction sécurisée de l'URL de checkout mobile avec présélection opérateur (airtel/moov), deep link de retour et blocage des clés secrètes (4/4 tests validés).
npm install ./packages/react-native
Compatible Expo & React Native CLI (non publié sur npm public)
Voir le guide React Native complet →
Qualifié Localement · Serveur
v1.0.0
5. Python SDK
SDK Python 3.10+ sans dépendance externe pour Django, FastAPI, Flask et Odoo. Couvre devis, paiements, checkout, QR, remboursements sandbox, lecture trésorerie/règlements/décaissements et anti-SSRF socket (34/34 tests validés).
pip install ./packages/sdk-python
Package local chadpay-python v1.0.0 (non publié sur PyPI public)
Voir le guide Python complet →
Qualifié Localement · Serveur
v1.0.0
6. Java & Spring Boot
SDK officiel Java 17+ sans dépendance runtime (com.chadpay:chadpay-java) pour Spring Boot 3, Jakarta EE et microservices JVM. Basé sur java.net.http.HttpClient avec builders, SsrfValidator et ChadPayWebhook (37/37 tests JUnit 5 validés).
mvn install -f packages/sdk-java/pom.xml
Artefact Maven local com.chadpay:chadpay-java:1.0.0 (non publié sur Maven Central)
Voir le guide Java 17+ complet →
Qualifié Localement · Mobile
v1.0.0
7. Flutter & Dart
SDK mobile officiel Flutter (chadpay_flutter) pour Android et iOS (Dart ^3.10.0, Flutter >=3.38.0). Inclut ChadPayCheckoutSheet et ChadPayCheckoutButton, résolution QR public, validation MSISDN +235 et requiresServerVerification=true (14/14 tests validés).
path: ../packages/sdk-flutter
Dépendance locale pubspec chadpay_flutter (non publié sur pub.dev)
Voir le guide Flutter complet →
Guides d'Intégration Détaillés des 7 SDKs Officiels
Chaque fiche technique ci-dessous présente les 9 rubriques obligatoires : vue d'ensemble, cas d'usage, prérequis, installation locale honnête, initialisation, exemple de paiement ou checkout vérifié, gestion des erreurs, sécurité et référence documentaire.
1 · BACKEND SERVER SDK
PHP SDK — chadpay/chadpay-php (v1.0.0)
packages/sdk-php · 52/52 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
Client PHP PSR-4 officiel pour la création de devis, l'initiation de paiements Mobile Money, les sessions Hosted Checkout, les QR statiques/dynamiques et la vérification des webhooks dans Laravel, Symfony et les CMS e-commerce.
3. Prérequis
PHP >= 8.1 (validé sur PHP 8.3.27), extensions standard ext-curl et ext-json. Aucune dépendance externe requise.
9. Référence & Statut de publication
packages/sdk-php/README.md · Qualifié localement (v1.0.0) — Non publié sur Packagist public.
4. Installation locale (Dépôt Composer local)
// composer.json (dépôt local — non encore publié sur Packagist)
{
"repositories": [
{ "type": "path", "url": "./packages/sdk-php" }
],
"require": {
"chadpay/chadpay-php": "^1.0"
}
}
5. Initialisation, 6. Exemple de Paiement/Checkout & 7. Gestion des Erreurs
<?php
use ChadPay\ChadPayClient;
use ChadPay\Exceptions\ChadPayException;
use ChadPay\Exceptions\ChadPayRateLimitException;
use ChadPay\Webhooks\Webhook;
// 5. Initialisation (clé secrète serveur uniquement)
$client = new ChadPayClient([
'apiKey' => $_ENV['CHADPAY_API_KEY'], // cp_test_... ou cp_live_...
'environment' => 'sandbox', // 'sandbox' ou 'live'
'timeoutSeconds' => 15,
'maxRetries' => 2,
]);
try {
// 6. Création d'un devis puis d'une session Hosted Checkout en XAF entier
$quote = $client->quotes->create([
'amount' => 15000,
'currency' => 'XAF',
'paymentMethod' => 'airtel_money',
]);
$session = $client->checkout->createSession([
'amount' => 15000,
'currency' => 'XAF',
'merchantReference' => 'ORD-2026-001',
'successUrl' => 'https://maboutique.td/checkout/success',
'cancelUrl' => 'https://maboutique.td/checkout/cancel',
'customerEmail' => 'client@maboutique.td',
], 'idem-checkout-ord-2026-001');
// Vérification cryptographique d'un webhook entrant (avec support rotation de secret)
$event = Webhook::constructEvent(
[$_ENV['CHADPAY_WEBHOOK_SECRET']],
$_SERVER['HTTP_X_CHADPAY_SIGNATURE'] ?? '',
$_SERVER['HTTP_X_CHADPAY_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_CHADPAY_EVENT_ID'] ?? '',
(string) file_get_contents('php://input'),
300
);
} catch (ChadPayRateLimitException $e) {
// 7. Gestion typée des erreurs (401, 403, 404, 409, 422, 429, 500)
error_log('Rate limited, retry after: ' . $e->getRetryAfterSeconds() . 's');
} catch (ChadPayException $e) {
error_log('ChadPay error (' . $e->getHttpStatus() . '): ' . $e->getMessage());
}
8. Sécurité & Bonnes pratiques :
Impose HTTPS en mode live, bloque les IP privées/loopback/metadata, épingle l'IP publique résolue via CURLOPT_RESOLVE contre le DNS rebinding, désactive les redirections HTTP et masque automatiquement les secrets dans les exceptions.
2 · BACKEND SERVER SDK
Node.js / TypeScript SDK — @chadpay/sdk (v1.0.0)
packages/sdk · 48/48 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
Client ESM strictement typé pour backends Node.js (AdonisJS, NestJS, Express, Fastify, routes serveur Next.js). Gère les devis, paiements, sessions checkout, QR statiques/dynamiques (SVG/PNG) et webhooks.
3. Prérequis
Node.js >= 18.0.0 (testé sur Node.js v24.20.0), TypeScript >= 5.0. Zéro dépendance runtime externe.
9. Référence & Statut de publication
packages/sdk/README.md · Qualifié localement (v1.0.0) — Non publié sur npm public.
4. Installation locale
# Compilation et installation depuis le chemin local du dépôt (non publié sur npm public)
cd packages/sdk && npm run build
npm install ./packages/sdk
5. Initialisation, 6. Exemple de Paiement/Checkout & 7. Gestion des Erreurs
import {
ChadPayClient,
ChadPayError,
ChadPayRateLimitError,
WebhooksService,
} from '@chadpay/sdk';
// 5. Initialisation
const client = new ChadPayClient({
apiKey: process.env.CHADPAY_API_KEY!,
environment: 'sandbox',
timeoutMs: 15000,
maxRetries: 2,
});
try {
// 6. Création d'une session Hosted Checkout
const session = await client.checkout.createSession({
amount: 25000,
currency: 'XAF',
merchantReference: 'CMD-99482',
description: 'Abonnement Cloud Fale Tech',
successUrl: 'https://mon-site.td/paiement/succes',
cancelUrl: 'https://mon-site.td/paiement/annule',
customer: { email: 'client@mon-site.td', phone: '+23566112233', name: 'Mahamat Ali' },
idempotencyKey: 'idem-cmd-99482',
});
// Vérification d'un webhook entrant avec WebhooksService
const webhooks = new WebhooksService();
const event = webhooks.constructEvent({
payload: rawRequestBody,
signatureHeader: req.headers['x-chadpay-signature'] as string,
timestamp: req.headers['x-chadpay-timestamp'] as string,
eventId: req.headers['x-chadpay-event-id'] as string,
secret: [process.env.CHADPAY_WEBHOOK_SECRET!],
});
} catch (err) {
// 7. Gestion typée des erreurs
if (err instanceof ChadPayRateLimitError) {
console.warn('Rate limited, retryAfterSeconds =', err.retryAfterSeconds);
} else if (err instanceof ChadPayError) {
console.error(`ChadPay API error [${err.status}]: ${err.message}`);
}
}
8. Sécurité & Bonnes pratiques :
Durci en Phase 8A contre le SSRF (blocage RFC1918, CGNAT, link-local, metadata cloud 169.254.169.254, IPv6 ULA/NAT64/mappées, IP obfusquées, redirections HTTP via redirect: "error" et résolution DNS A/AAAA préalable).
3 · WEB CLIENT SDK
React Web SDK — @chadpay/react (v0.2.0)
packages/react · 4/4 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
Hook React léger (useChadPayCheckout) pour applications web et boutiques en ligne. Ouvre le Hosted Checkout ChadPay en redirection ou fenêtre modale à partir d'un checkoutToken éphémère généré par votre backend.
3. Prérequis
React >= 18.0.0 (compatible React 18 & 19), navigateur moderne supportant window.postMessage.
9. Référence & Statut de publication
packages/react/README.md · Qualifié localement (v0.2.0) — Non publié sur npm public.
4. Installation locale
cd packages/react && npm run build
npm install ./packages/react
5. Initialisation, 6. Exemple Checkout & 7. Gestion des Erreurs
import React from 'react';
import { useChadPayCheckout, ChadPaySecurityError } from '@chadpay/react';
export function PayWithChadPayButton({ checkoutToken }: { checkoutToken: string }) {
// 5. Initialisation & 6. Ouverture du Checkout hébergé
const { checkoutUrl, openCheckout, isReady } = useChadPayCheckout({
checkoutToken, // ex: 'chk_test_...' généré par votre serveur backend
mode: 'modal',
baseUrl: 'https://chadpay.td',
onSuccess: (event) => {
// Vérifiez toujours le statut final sur votre backend avant de livrer la commande
window.location.href = `/orders/verify?paymentId=${encodeURIComponent(event.paymentId)}`;
},
onCancel: () => console.info('Checkout fermé par le client'),
onError: (err) => console.error('Erreur checkout:', err.code, err.message),
});
return (
<button type="button" onClick={openCheckout} disabled={!isReady} className="cp-public-button">
Payer avec ChadPay (Moov Money / Airtel Money)
</button>
);
}
7 & 8. Gestion des erreurs & Sécurité :
Lève immédiatement ChadPaySecurityError si une clé secrète (cp_live_*, cp_test_*, sec_live_*, sec_test_*, whsec_*, Bearer) ou une baseUrl non HTTPS/metadata est fournie. Vérifie strictement l'origine postMessage sur les domaines HTTPS exacts *.chadpay.td / *.chadpay.net.
4 · MOBILE CLIENT SDK
React Native & Expo SDK — @chadpay/react-native (v0.2.0)
packages/react-native · 4/4 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
Helper mobile (useChadPayMobile) pour applications React Native et Expo. Construit les URLs Hosted Checkout sécurisées pour navigateur intégré avec retour applicatif par deep link.
3. Prérequis
React >= 18.0.0, React Native >= 0.70.0 ou Expo SDK 50+.
9. Référence & Statut de publication
packages/react-native/README.md · Qualifié localement (v0.2.0) — Non publié sur npm public.
4. Installation locale
cd packages/react-native && npm run build
npm install ./packages/react-native
5. Initialisation, 6. Exemple Mobile Checkout & 7. Gestion des Erreurs
import { Linking } from 'react-native';
import { useChadPayMobile, ChadPayMobileSecurityError } from '@chadpay/react-native';
export function startMobilePayment(checkoutToken: string) {
try {
const { checkoutUrl, isReady } = useChadPayMobile({
checkoutToken,
baseUrl: 'https://chadpay.td',
returnUrl: 'myapp://checkout-complete',
preferredOperator: 'airtel',
});
if (isReady) {
await Linking.openURL(checkoutUrl);
}
} catch (err) {
if (err instanceof ChadPayMobileSecurityError) {
console.error('Configuration mobile rejetée :', err.message);
}
}
}
8. Sécurité & Bonnes pratiques :
Bloque tous les préfixes de clés secrètes marchandes, rejette les schémas dangereux dans returnUrl (javascript:, data:, file:) et impose la vérification serveur du paiement après le retour deep link.
5 · BACKEND SERVER SDK
Python SDK — chadpay-python (v1.0.0)
packages/sdk-python · 34/34 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
SDK Python backend officiel pour Django, FastAPI, Flask, Odoo et scripts de facturation. Couvre Devis, Paiements, Checkout, QR (SVG/PNG), Remboursements Sandbox et consultation Wallet/Règlements/Décaissements.
3. Prérequis
Python >= 3.10 (testé sur Python 3.14.7). Zéro dépendance externe runtime (bibliothèque standard uniquement, PEP 561 py.typed).
9. Référence & Statut de publication
packages/sdk-python/README.md · Qualifié localement (v1.0.0) — Non publié sur PyPI public.
4. Installation locale
# Installation directe depuis le répertoire local du dépôt (non publié sur PyPI)
pip install ./packages/sdk-python
5. Initialisation, 6. Exemple de Paiement/Checkout & 7. Gestion des Erreurs
import os
from chadpay import (
ChadPayClient,
ChadPayError,
ChadPayRateLimitError,
Webhook,
)
# 5. Initialisation avec gestionnaire de contexte
with ChadPayClient(
api_key=os.environ["CHADPAY_API_KEY"],
environment="sandbox",
timeout_seconds=15.0,
max_retries=2,
) as client:
try:
# 6. Création d'un devis puis initiation d'un paiement Mobile Money idempotent
quote = client.quotes.create(
{
"amount": 15000,
"currency": "XAF",
"paymentMethod": "airtel_money",
}
)
payment = client.payments.create(
{
"quoteId": quote.get("quoteId") or quote.get("id"),
"amount": 15000,
"currency": "XAF",
"paymentMethod": "airtel_money",
"customerPhone": "+23566112233",
"merchantReference": "ORD-PY-2026-01",
},
idempotency_key="idem-ord-py-2026-01",
)
# Vérification cryptographique d'un webhook entrant
event = Webhook.construct_event(
secret=[os.environ["CHADPAY_WEBHOOK_SECRET"]],
signature_header=request_headers["X-ChadPay-Signature"],
timestamp=request_headers.get("X-ChadPay-Timestamp", ""),
event_id=request_headers["X-ChadPay-Event-Id"],
body=raw_request_body,
)
except ChadPayRateLimitError as exc:
# 7. Gestion typée des exceptions
print(f"Rate limit atteint, réessayer dans {exc.retry_after_seconds}s")
except ChadPayError as exc:
print(f"Erreur ChadPay ({exc.status}): {exc}")
8. Sécurité & Bonnes pratiques :
Valide les montants entiers XAF (rejette floats et booléens), applique la vérification DNS anti-SSRF ainsi que le contrôle de l'IP pair du socket TCP (_PeerIpVerifiedHTTPSHandler) contre le DNS rebinding, bloque les redirections 3xx et interdit les appels refund en mode live.
6 · BACKEND SERVER SDK
Java 17+ SDK — com.chadpay:chadpay-java (v1.0.0)
packages/sdk-java · 37/37 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
SDK officiel Java 17+ pour Spring Boot 3, Jakarta EE, Quarkus et intégrations ERP/bancaires. Client thread-safe AutoCloseable avec builders fluides et zéro dépendance externe au runtime.
3. Prérequis
Java 17+ (compilé avec --release 17, testé sur OpenJDK 21.0.9), Apache Maven 3.9+ ou Gradle.
9. Référence & Statut de publication
packages/sdk-java/README.md · Qualifié localement (v1.0.0) — Non publié sur Maven Central.
4. Installation locale (Dépôt Maven local ~/.m2)
# 1. Installer l'artefact dans votre dépôt local ~/.m2 (non encore publié sur Maven Central)
mvn clean install -f packages/sdk-java/pom.xml
# 2. Déclarer la dépendance dans le pom.xml de votre projet
<dependency>
<groupId>com.chadpay</groupId>
<artifactId>chadpay-java</artifactId>
<version>1.0.0</version>
</dependency>
5. Initialisation, 6. Exemple de Paiement/Checkout & 7. Gestion des Erreurs
import com.chadpay.ChadPayClient;
import com.chadpay.ChadPayEnvironment;
import com.chadpay.exception.ChadPayException;
import com.chadpay.exception.ChadPayRateLimitException;
import com.chadpay.model.CheckoutSessionCreateRequest;
import com.chadpay.webhook.ChadPayWebhook;
import com.chadpay.webhook.WebhookEvent;
import java.time.Duration;
import java.util.List;
import java.util.Map;
// 5. Initialisation du client thread-safe
try (ChadPayClient client = ChadPayClient.builder()
.apiKey(System.getenv("CHADPAY_API_KEY"))
.environment(ChadPayEnvironment.SANDBOX)
.timeout(Duration.ofSeconds(15))
.maxRetries(2)
.buildClient()) {
// 6. Création d'une session Hosted Checkout avec builder typé
Map<String, Object> session = client.checkout().createSession(
CheckoutSessionCreateRequest.builder()
.amount(25_000L)
.merchantReference("INV-JAVA-2026-01")
.customerName("Mahamat Saleh")
.customerPhone("+23566112233")
.customerEmail("mahamat@example.td")
.successUrl("https://merchant.example.td/success")
.cancelUrl("https://merchant.example.td/cancel")
.idempotencyKey(ChadPayClient.generateIdempotencyKey())
.build()
);
// Vérification de signature Webhook HMAC-SHA256 en temps constant
WebhookEvent event = ChadPayWebhook.constructEvent(
List.of(System.getenv("CHADPAY_WEBHOOK_SECRET")),
signatureHeader,
timestampHeader,
eventIdHeader,
rawRequestBody
);
} catch (ChadPayRateLimitException ex) {
// 7. Gestion typée des exceptions
System.err.println("Rate limit, Retry-After = " + ex.getRetryAfterSeconds());
} catch (ChadPayException ex) {
System.err.println("ChadPay HTTP " + ex.getStatusCode() + ": " + ex.getMessage());
}
8. Sécurité & Bonnes pratiques :
Basé sur java.net.http.HttpClient avec Redirect.NEVER, SsrfValidator complet (blocage RFC1918, CGNAT, loopback, link-local, metadata cloud, IPv6 ULA/NAT64, IP obfusquées et vérification DNS InetAddress.getAllByName), comparaison HMAC en temps constant MessageDigest.isEqual et SecretSanitizer.
7 · MOBILE CLIENT SDK (ANDROID & IOS)
Flutter / Dart SDK — chadpay_flutter (v1.0.0)
packages/sdk-flutter · 14/14 tests PASS
1. Vue d'ensemble & 2. Cas d'usage
SDK mobile officiel Flutter pour applications Android et iOS. Consomme les sessions publiques (/v1/public/checkout/sessions/{token}) et les QR publics (/v1/public/qr/*), avec les widgets prêts à l'emploi ChadPayCheckoutButton et ChadPayCheckoutSheet.
3. Prérequis
Dart ^3.10.0, Flutter >=3.38.0 (vérifié sur Flutter 3.38.5 / Dart 3.10.4). Zéro dépendance tierce externe.
9. Référence & Statut de publication
packages/sdk-flutter/README.md · Qualifié localement (v1.0.0) — Non publié sur pub.dev.
4. Installation locale (dépendance path dans pubspec.yaml)
# pubspec.yaml (dépendance locale — non encore publié sur pub.dev)
dependencies:
flutter:
sdk: flutter
chadpay_flutter:
path: ../packages/sdk-flutter
5. Initialisation, 6. Exemple Widget Mobile Checkout & 7. Gestion des Erreurs
import 'package:chadpay_flutter/chadpay_flutter.dart';
import 'package:flutter/material.dart';
// 5. Initialisation sans aucune clé secrète (consomme uniquement un publicToken créé par votre backend)
final chadPay = ChadPayFlutter(
environment: ChadPayEnvironment.sandbox,
);
// 6. Affichage du bouton et de la feuille de paiement (Light/Dark, >=48dp touch targets, Dynamic Type)
ChadPayCheckoutButton(
client: chadPay,
session: const ChadPayCheckoutSession(
publicToken: 'cstok_test_session_from_merchant_backend',
amount: 15000,
merchantName: 'Boutique Fale Tech',
description: 'Commande #2026-42',
),
onResult: (ChadPayCheckoutResult result) async {
// 7 & 8. requiresServerVerification est TOUJOURS true : confirmez sur votre backend !
if (result.isSucceeded && result.requiresServerVerification) {
await myBackendApi.confirmOrderStatus(result.publicToken, result.paymentId);
}
},
);
8. Sécurité & Bonnes pratiques :
Rejette tout préfixe de clé secrète (cp_live_*, cp_test_*, sec_live_*, sec_test_*, whsec_*, Bearer), interdit toute donnée brute de carte bancaire (cardNumber, pan, cvv, pin), bloque les redirections 3xx et hôtes SSRF privés/metadata, valide les MSISDN tchadiens (+235) et impose requiresServerVerification = true sur chaque résultat mobile.