OpenAPI et SDK

Toute l’API est décrite dans une spécification OpenAPI 3.1, à partir de laquelle sont fournis une collection Postman et trois SDK officiels : Node.js, PHP et Python. Les SDK couvrent chaque endpoint, passent livemode tel quel, et embarquent la vérification de signature des webhooks.

Spécification et Postman

Fichier	Adresse
OpenAPI 3.1 (JSON)	cartflox.com/docs/openapi.json
OpenAPI 3.1 (YAML)	cartflox.com/docs/openapi.yaml
Collection Postman (v2.1)	cartflox.com/docs/cartflox.postman_collection.json
Index pour les assistants (llms.txt)	cartflox.com/llms.txt, llms-full.txt

Dans Postman : Import, puis collez l’adresse de la collection. Renseignez la variable bearerToken avec votre clé secrète (de test pour commencer). Pour un autre langage (Go, Java, C#, Ruby…), générez un client depuis la spécification avec openapi-generator.

Installer un SDK

Publication sur les registres

Les SDK ne sont pas encore publiés sur npm, Packagist ni PyPI : installez-les depuis les archives ci-dessous. N’installez aucun paquet cartflox venu d’ailleurs.

Node.js

Node.js 18 ou plus, aucune dépendance, TypeScript inclus, ESM et CommonJS.

curl -O https://cartflox.com/docs/sdk/cartflox-node.tgz
npm install ./cartflox-node.tgz

PHP

PHP 8.0 ou plus, extensions cURL et JSON. L’archive s’installe comme un dépôt « artifact » de Composer :

mkdir -p vendor-cartflox && curl -o vendor-cartflox/cartflox-php.zip https://cartflox.com/docs/sdk/cartflox-php.zip
composer config repositories.cartflox artifact ./vendor-cartflox
composer require cartflox/cartflox

Python

Python 3.9 ou plus, bibliothèque standard seulement.

pip install https://cartflox.com/docs/sdk/cartflox-python.zip

Créer une session

Node.js

import { Cartflox } from "cartflox";

const cartflox = new Cartflox({ apiKey: process.env.CARTFLOX_SECRET_KEY });

const session = await cartflox.checkout.sessions.create(
  { amount: 5000, currency: "XOF", customer_email: "awa@example.com", metadata: { order_id: "1042" } },
  { idempotencyKey: "commande-1042" },
);
// Redirigez le client vers session.url, puis attendez le webhook payment.completed
const statut = await cartflox.checkout.sessions.retrieveStatus(session.id);
if (statut.paid) { /* livrer */ }

PHP

use Cartflox\Cartflox;

$cartflox = new Cartflox(getenv('CARTFLOX_SECRET_KEY'));

$session = $cartflox->checkout->sessions->create([
    'amount' => 5000, 'currency' => 'XOF', 'customer_email' => 'awa@example.com', 'metadata' => ['order_id' => '1042'],
], ['idempotencyKey' => 'commande-1042']);
header('Location: ' . $session['url']);

Python

from cartflox import Cartflox

cartflox = Cartflox(os.environ["CARTFLOX_SECRET_KEY"])

session = cartflox.checkout.sessions.create(
    {"amount": 5000, "currency": "XOF", "customer_email": "awa@example.com", "metadata": {"order_id": "1042"}},
    idempotency_key="commande-1042",
)
statut = cartflox.checkout.sessions.retrieve_status(session["id"])

Vérifier un webhook

Chaque SDK vérifie la signature (X-Afriflow-Signature, X-Afriflow-Timestamp, tolérance de 5 minutes) et rend l’événement décodé. Passez le corps brut de la requête, jamais un JSON déjà analysé.

Node.js

import { Webhooks, WebhookSignatureError } from "cartflox";

app.post("/webhooks/cartflox", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = Webhooks.constructEvent(req.body, req.get("X-Afriflow-Signature"), req.get("X-Afriflow-Timestamp"), process.env.CARTFLOX_SECRET_KEY);
    if (event.event === "payment.completed" && event.livemode) { /* livrer event.data.order_id */ }
    res.sendStatus(200);
  } catch (e) {
    if (e instanceof WebhookSignatureError) return res.sendStatus(400);
    throw e;
  }
});

PHP

use Cartflox\Webhook;

$event = Webhook::constructEvent(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_AFRIFLOW_SIGNATURE'] ?? '',
    $_SERVER['HTTP_X_AFRIFLOW_TIMESTAMP'] ?? '',
    getenv('CARTFLOX_SECRET_KEY')
);
if ($event['event'] === 'payment.completed' && $event['livemode']) { /* livrer */ }
http_response_code(200);

Python

from cartflox import Webhook

event = Webhook.construct_event(
    request.get_data(),
    request.headers.get("X-Afriflow-Signature"),
    request.headers.get("X-Afriflow-Timestamp"),
    os.environ["CARTFLOX_SECRET_KEY"],
)
if event["event"] == "payment.completed" and event["livemode"]:
    ...  # livrer

Mode test dans les SDK

Donnez au client votre clé secrète de test (af_test_sec_...) : rien d’autre ne change. isTestKey (Node et PHP) ou is_test_key (Python) dit quelle clé le client porte, et checkout.sessions.simulate(id, issue) dénoue une session de test sans ouvrir la page, pour vos tests automatisés. Voir Mode test.

Ce que couvrent les SDK

Sessions (créer, statut, moyens, simuler), liens de paiement, transferts (créer, lire, lister, options), livraisons de webhooks (lister, lire, renvoyer), configuration du webhook, routage, export des transactions, et l’API partenaire. Chaque méthode rend le JSON complet de la réponse ; les erreurs HTTP lèvent CartfloxError (Node), CartfloxException (PHP) ou CartfloxError (Python) avec le statut, le code et le message.