Qualified Locally · Server
v1.0.0
1. PHP SDK
Official backend SDK for PHP 8.1+, Laravel, and Symfony. Supports quotes, payments, checkout sessions, static/dynamic QR, anti-SSRF with CURLOPT_RESOLVE IP pinning, and HMAC-SHA256 webhooks (52/52 tests passed).
packages/sdk-php · chadpay/chadpay-php
Local Composer path repository / verified archive (not yet on Packagist)
View PHP guide & code →
Qualified Locally · Server
v1.0.0
2. Node.js / TypeScript Core
Zero-dependency ESM/TypeScript SDK for Node.js 18+, AdonisJS, NestJS, Express, and Next.js server routes. Full anti-SSRF DNS validation, idempotent retries, and WebhooksService (48/48 tests passed).
npm install ./packages/sdk
Local tarball / workspace package @chadpay/sdk (not yet on public npm)
View TypeScript guide & code →
Qualified Locally · Web Client
v0.2.0
3. React Web Components
Frontend hook useChadPayCheckout for React 18/19 web apps. Supports redirect and modal popup checkout with strict origin verification and automatic secret key rejection (4/4 tests passed).
npm install ./packages/react
Consumes public checkoutToken only (not yet on public npm)
View React guide & code →
Qualified Locally · Mobile
v0.2.0
4. React Native & Expo
Mobile checkout helper useChadPayMobile for React Native & Expo. Formats hosted checkout URLs with operator pre-selection (airtel/moov), safe deep-link returnUrl, and secret key blocking (4/4 tests passed).
npm install ./packages/react-native
Compatible with Expo & React Native CLI (not yet on public npm)
View React Native guide & code →
Qualified Locally · Server
v1.0.0
5. Python SDK
Zero-external-dependency Python 3.10+ SDK for Django, FastAPI, Flask, and Odoo. Covers quotes, payments, checkout, QR, sandbox refunds, read-only settlements/wallet/payouts, and socket peer-IP anti-SSRF (34/34 tests passed).
pip install ./packages/sdk-python
Local package chadpay-python v1.0.0 (not yet published on PyPI)
View Python guide & code →
Qualified Locally · Server
v1.0.0
6. Java & Spring Boot
Zero-runtime-dependency Java 17+ SDK (com.chadpay:chadpay-java) for Spring Boot 3, Jakarta EE, and JVM microservices. Built on java.net.http.HttpClient with builder DTOs, SsrfValidator, and ChadPayWebhook (37/37 JUnit 5 tests passed).
mvn install -f packages/sdk-java/pom.xml
Local Maven artifact com.chadpay:chadpay-java:1.0.0 (not yet on Maven Central)
View Java 17+ guide & code →
Qualified Locally · Mobile
v1.0.0
7. Flutter & Dart
Official Flutter mobile SDK (chadpay_flutter) for Android & iOS (Dart ^3.10.0, Flutter >=3.38.0). Includes ChadPayCheckoutSheet & ChadPayCheckoutButton, public QR resolution, +235 MSISDN validation, and requiresServerVerification=true (14/14 tests passed).
path: ../packages/sdk-flutter
Local pubspec path dependency chadpay_flutter (not yet published on pub.dev)
View Flutter guide & code →
Detailed Integration Guides for All 7 Official SDKs
Each SDK reference below includes its overview, use cases, prerequisites, local installation procedure, initialization, verified payment/checkout code example, error handling, security rules, and documentation reference.
1 · BACKEND SERVER SDK
PHP SDK — chadpay/chadpay-php (v1.0.0)
packages/sdk-php · 52/52 tests PASS
1. Overview & 2. Use Cases
Official PSR-4 PHP client for server-side payment initiation, quote creation, hosted checkout sessions, static/dynamic POS QR codes, and webhook verification in Laravel, Symfony, WordPress/WooCommerce, PrestaShop, and WHMCS.
3. Prerequisites
PHP >= 8.1 (validé sur PHP 8.3.27), extensions standard ext-curl et ext-json. Aucune dépendance externe requise.
9. Docs & Real Publication Status
packages/sdk-php/README.md · Qualified locally (v1.0.0) — Not yet published on Packagist.
4. Local Installation (Composer Path Repository)
// composer.json (local repository path — not yet published on Packagist)
{
"repositories": [
{ "type": "path", "url": "./packages/sdk-php" }
],
"require": {
"chadpay/chadpay-php": "^1.0"
}
}
5. Initialization, 6. Payment/Checkout & 7. Error Handling
<?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. Security & Best Practices:
Enforces HTTPS in live mode, blocks private/loopback/metadata IPs, pins validated DNS IPs at the cURL socket layer via CURLOPT_RESOLVE against DNS rebinding, disables HTTP redirects, and automatically redacts secrets from exception messages.
2 · BACKEND SERVER SDK
Node.js / TypeScript SDK — @chadpay/sdk (v1.0.0)
packages/sdk · 48/48 tests PASS
1. Overview & 2. Use Cases
Strictly typed ESM client for Node.js backends (AdonisJS, NestJS, Express, Fastify, Next.js API routes). Manages quotes, payments, checkout sessions, static/dynamic QR rendering (SVG/PNG), and webhook verification.
3. Prerequisites
Node.js >= 18.0.0 (testé sur Node.js v24.20.0), TypeScript >= 5.0. Zéro dépendance runtime externe.
9. Docs & Real Publication Status
packages/sdk/README.md · Qualified locally (v1.0.0) — Not yet published on public npm.
4. Local Installation
# Build and install from the local repository path (not yet published on public npm)
cd packages/sdk && npm run build
npm install ./packages/sdk
5. Initialization, 6. Payment/Checkout & 7. Error Handling
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. Security & Best Practices:
Hardened in Phase 8A against SSRF (blocks RFC1918, CGNAT, link-local, cloud metadata 169.254.169.254, IPv6 ULA/NAT64/mapped, obfuscated IP encodings, and HTTP redirects via redirect: "error" + pre-flight DNS A/AAAA verification).
3 · WEB CLIENT SDK
React Web SDK — @chadpay/react (v0.2.0)
packages/react · 4/4 tests PASS
1. Overview & 2. Use Cases
Lightweight React hook (useChadPayCheckout) for single-page applications and e-commerce storefronts. Opens ChadPay Hosted Checkout via full-page redirect or centered popup modal using an ephemeral checkoutToken.
3. Prerequisites
React >= 18.0.0 (compatible React 18 & 19), navigateur moderne supportant window.postMessage.
9. Docs & Real Publication Status
packages/react/README.md · Qualified locally (v0.2.0) — Not yet published on public npm.
4. Local Installation
cd packages/react && npm run build
npm install ./packages/react
5. Initialization, 6. Checkout Example & 7. Error Handling
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. Error Handling & Security:
Throws ChadPaySecurityError immediately if a secret key (cp_live_*, cp_test_*, sec_live_*, sec_test_*, whsec_*, Bearer) or an unsafe non-HTTPS/metadata baseUrl is passed. Validates postMessage origin against exact *.chadpay.td / *.chadpay.net HTTPS domains.
4 · MOBILE CLIENT SDK
React Native & Expo SDK — @chadpay/react-native (v0.2.0)
packages/react-native · 4/4 tests PASS
1. Overview & 2. Use Cases
Mobile checkout helper (useChadPayMobile) for React Native and Expo apps. Builds safe Hosted Checkout URLs for In-App Browser (expo-web-browser / react-native-inappbrowser) with deep-link return URLs.
3. Prerequisites
React >= 18.0.0, React Native >= 0.70.0 ou Expo SDK 50+.
9. Docs & Real Publication Status
packages/react-native/README.md · Qualified locally (v0.2.0) — Not yet published on public npm.
4. Local Installation
cd packages/react-native && npm run build
npm install ./packages/react-native
5. Initialization, 6. Mobile Checkout & 7. Error Handling
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. Security & Best Practices:
Blocks all merchant secret key prefixes (cp_live_*, cp_test_*, sec_live_*, sec_test_*, whsec_*), rejects dangerous returnUrl schemes (javascript:, data:, file:), and requires backend verification of the payment status after deep-link return.
5 · BACKEND SERVER SDK
Python SDK — chadpay-python (v1.0.0)
packages/sdk-python · 34/34 tests PASS
1. Overview & 2. Use Cases
Official Python backend SDK for Django, FastAPI, Flask, Odoo, and billing scripts. Provides Quotes, Payments, Checkout, QR (Static/Dynamic SVG/PNG), Sandbox Refunds, and read-only Settlements/Wallet/Payouts.
3. Prerequisites
Python >= 3.10 (testé sur Python 3.14.7). Zéro dépendance externe runtime (bibliothèque standard uniquement, PEP 561 py.typed).
9. Docs & Real Publication Status
packages/sdk-python/README.md · Qualified locally (v1.0.0) — Not yet published on PyPI.
4. Local Installation
# Install directly from the local repository directory (not yet published on PyPI)
pip install ./packages/sdk-python
5. Initialization, 6. Payment/Checkout & 7. Error Handling
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. Security & Best Practices:
Validates integer XAF amounts (rejects floats and booleans), enforces pre-flight DNS SSRF checks plus socket-level peer IP verification (_PeerIpVerifiedHTTPSHandler) against DNS rebinding, blocks 3xx redirects, and blocks live refund calls client-side.
6 · BACKEND SERVER SDK
Java 17+ SDK — com.chadpay:chadpay-java (v1.0.0)
packages/sdk-java · 37/37 tests PASS
1. Overview & 2. Use Cases
Official Java 17+ SDK for Spring Boot 3, Jakarta EE, Quarkus, and enterprise ERP/core-banking integrations. Thread-safe, AutoCloseable client with fluent request builders and zero external runtime dependencies.
3. Prerequisites
Java 17+ (compilé avec --release 17, testé sur OpenJDK 21.0.9), Apache Maven 3.9+ ou Gradle.
9. Docs & Real Publication Status
packages/sdk-java/README.md · Qualified locally (v1.0.0) — Not yet published on Maven Central.
4. Local Installation (Maven Local Repository)
# 1. Install the artifact into your local ~/.m2 repository (not yet on Maven Central)
mvn clean install -f packages/sdk-java/pom.xml
# 2. Declare the dependency in your project pom.xml
<dependency>
<groupId>com.chadpay</groupId>
<artifactId>chadpay-java</artifactId>
<version>1.0.0</version>
</dependency>
5. Initialization, 6. Payment/Checkout & 7. Error Handling
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. Security & Best Practices:
Built on java.net.http.HttpClient with Redirect.NEVER, SsrfValidator (blocks RFC1918, CGNAT, loopback, link-local, cloud metadata, IPv6 ULA/NAT64, obfuscated IPs, and pre-flight InetAddress.getAllByName DNS resolution), constant-time MessageDigest.isEqual HMAC comparison, and SecretSanitizer.
7 · MOBILE CLIENT SDK (ANDROID & IOS)
Flutter / Dart SDK — chadpay_flutter (v1.0.0)
packages/sdk-flutter · 14/14 tests PASS
1. Overview & 2. Use Cases
Official Flutter mobile SDK for Android and iOS apps. Consumes public checkout sessions (/v1/public/checkout/sessions/{token}) and public static/dynamic QR endpoints (/v1/public/qr/*), with ready-to-use ChadPayCheckoutButton and ChadPayCheckoutSheet widgets.
3. Prerequisites
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. Docs & Real Publication Status
packages/sdk-flutter/README.md · Qualified locally (v1.0.0) — Not yet published on pub.dev.
4. Local Installation (pubspec.yaml path dependency)
# pubspec.yaml (local path dependency — not yet published on pub.dev)
dependencies:
flutter:
sdk: flutter
chadpay_flutter:
path: ../packages/sdk-flutter
5. Initialization, 6. Mobile Checkout Widget & 7. Error Handling
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. Security & Best Practices:
Rejects any secret key prefix (cp_live_*, cp_test_*, sec_live_*, sec_test_*, whsec_*, Bearer), rejects raw PCI card data (cardNumber, pan, cvv, pin), blocks 3xx redirects and private/metadata SSRF hosts, validates Chad (+235) MSISDNs, and enforces requiresServerVerification = true on every mobile result.