OpenAPI and SDKs

The whole API is described in an OpenAPI 3.1 specification, from which a Postman collection and three official SDKs are provided: Node.js, PHP and Python. The SDKs cover every endpoint, pass livemode through untouched, and ship with webhook signature verification.

Specification and Postman

File	Address
OpenAPI 3.1 (JSON)	cartflox.com/docs/openapi.json
OpenAPI 3.1 (YAML)	cartflox.com/docs/openapi.yaml
Postman collection (v2.1)	cartflox.com/docs/cartflox.postman_collection.json
Index for AI assistants (llms.txt)	cartflox.com/llms.txt, llms-full.txt

In Postman: Import, then paste the collection address. Set the bearerToken variable to your secret key (the test one to start with). For another language (Go, Java, C#, Ruby…), generate a client from the specification with openapi-generator.

Install an SDK

Registry publication

The SDKs are not published on npm, Packagist or PyPI yet: install them from the archives below. Do not install any cartflox package from anywhere else.

Node.js

Node.js 18 or newer, no dependency, TypeScript included, ESM and CommonJS.

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

PHP

PHP 8.0 or newer, cURL and JSON extensions. The archive installs as a Composer “artifact” repository:

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 or newer, standard library only.

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

Create a 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: "order-1042" },
);
// Redirect the customer to session.url, then wait for the payment.completed webhook
const status = await cartflox.checkout.sessions.retrieveStatus(session.id);
if (status.paid) { /* fulfil */ }

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' => 'order-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="order-1042",
)
status = cartflox.checkout.sessions.retrieve_status(session["id"])

Verify a webhook

Each SDK verifies the signature (X-Afriflow-Signature, X-Afriflow-Timestamp, 5-minute tolerance) and returns the decoded event. Pass the raw request body, never an already parsed JSON.

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) { /* fulfil 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']) { /* fulfil */ }
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"]:
    ...  # fulfil

Test mode in the SDKs

Give the client your test secret key (af_test_sec_...): nothing else changes. isTestKey (Node and PHP) or is_test_key (Python) tells you which key the client holds, and checkout.sessions.simulate(id, issue) settles a test session without opening the page, for your automated tests. See Test mode.

What the SDKs cover

Sessions (create, status, methods, simulate), payment links, transfers (create, retrieve, list, options), webhook deliveries (list, retrieve, resend), webhook configuration, routing, transaction export, and the partner API. Each method returns the full JSON of the response; HTTP errors raise CartfloxError (Node), CartfloxException (PHP) or CartfloxError (Python) with the status, the code and the message.