Documentation développeur

# Sandbox (tests)
https://sandbox.api.cartflox.com/v2

# Production
https://api.cartflox.com/v2

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_01HXYZ...",
    "timestamp": "2026-03-01T12:00:00Z"
  }
}

// En cas d'erreur :
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Le solde du compte est insuffisant.",
    "details": {}
  }
}

CARTFLOX_SECRET_KEY=cf_live_sec_xxxxxxxxxxxxxxxxxxxxxxxx
CARTFLOX_PUBLIC_KEY=cf_live_pub_xxxxxxxxxxxxxxxxxxxxxxxx
CARTFLOX_BASE_URL=https://cartflox.com

const response = await fetch(
  `${process.env.CARTFLOX_BASE_URL}/api/v1/checkout/sessions`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.CARTFLOX_SECRET_KEY}`,
    },
    body: JSON.stringify({
      amount: 5000,
      currency: "XOF",
      customer_name: "Kouassi Jean",
      customer_email: "client@example.com",
      customer_phone: "+22507070707",
      description: "Commande #order_123",
      success_url: "https://monsite.com/paiement/succes",
      cancel_url: "https://monsite.com/paiement/annule",
      metadata: { orderId: "order_123" },
    }),
  }
);

const session = await response.json();

// Rediriger le client vers la page de paiement
console.log(session.url);
// → https://cartflox.com/checkout/cmmtlfj27...

curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer cf_live_sec_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://monsite.com/api/webhooks/cartflox" }'

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const { event, data } = await req.json();

  if (event === "payment.completed") {
    // ✅ Mettre à jour votre base de données
    await db.orders.update({
      where: { cartfloxId: data.id },
      data: { status: "paid" }
    });
  }

  return NextResponse.json({ received: true });
}

const res = await fetch(
  `${process.env.CARTFLOX_BASE_URL}/api/v1/checkout/sessions/${sessionId}`,
  { headers: { "Authorization": `Bearer ${process.env.CARTFLOX_SECRET_KEY}` } }
);
const session = await res.json();

if (session.status === "SUCCESS") {
  console.log("Paiement reçu :", session.amount, session.currency);
}

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl https://cartflox.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer cf_live_sec_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

import Cartflox from "@cartflox/node";

const cartflox = new Cartflox(process.env.CARTFLOX_SECRET_KEY!);
// Le SDK gère automatiquement l'authentification

const payment = await cartflox.payments.create({
  amount: 25000,
  currency: "XOF",
  method: "wave",
  customer: {
    phone: "+22507070707",
    email: "client@example.com",
    name: "Kouassi Jean"
  },
  description: "Abonnement Premium - Janvier 2026",
  redirectUrl: "https://monsite.com/success",
  cancelUrl: "https://monsite.com/cancel",
  metadata: {
    orderId: "ORD-2026-001",
    userId: "usr_123"
  }
});

// Rediriger le client
res.redirect(payment.checkoutUrl);

curl -X POST https://cartflox.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer cf_live_sec_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XOF",
    "customer_name": "Kouassi Jean",
    "customer_email": "client@example.com",
    "customer_phone": "+22507070707",
    "description": "Abonnement Premium",
    "success_url": "https://monsite.com/success",
    "cancel_url": "https://monsite.com/cancel"
  }'

{
  "id": "cmmtlfj27000004l4nuzy1zz5",
  "object": "checkout.session",
  "url": "https://cartflox.com/checkout/cmmtlfj27000004l4nuzy1zz5",
  "order_id": "CS-MMTLFJ1Z-B4HEE",
  "amount": 25000,
  "currency": "XOF",
  "status": "pending",
  "created": "2026-03-01T12:00:00Z"
}

const payment = await cartflox.payments.retrieve("pi_01HXYZ789ABC");

switch (payment.status) {
  case "completed":
    await fulfillOrder(payment.metadata.orderId);
    break;
  case "failed":
    await notifyCustomerOfFailure(payment.customer.email);
    break;
  default:
    console.log("Statut:", payment.status);
}

curl https://cartflox.com/api/v1/checkout/sessions/cmmtlfj27000004l4nuzy1zz5 \
  -H "Authorization: Bearer cf_live_sec_xxxx"

{
  "id": "cmmtlfj27000004l4nuzy1zz5",
  "object": "checkout.session",
  "url": "https://cartflox.com/checkout/cmmtlfj27000004l4nuzy1zz5",
  "order_id": "CS-MMTLFJ1Z-B4HEE",
  "amount": 25000,
  "currency": "XOF",
  "status": "SUCCESS",
  "created": "2026-03-01T12:00:00Z"
}

const payments = await cartflox.payments.list({
  limit: 20,
  status: "completed",
  currency: "XOF",
  from: "2026-01-01T00:00:00Z",
  to:   "2026-03-01T23:59:59Z"
});

for (const payment of payments.data) {
  console.log(payment.id, payment.amount, payment.status);
}

// Pagination
if (payments.hasMore) {
  const nextPage = await cartflox.payments.list({
    cursor: payments.nextCursor
  });
}

curl "https://api.cartflox.com/v2/payments?limit=20&status=completed&currency=XOF" \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "success": true,
  "data": [
    {
      "id": "pi_01HXYZ789ABC",
      "status": "completed",
      "amount": 25000,
      "currency": "XOF",
      "method": "wave",
      "customer": { "phone": "+22507070707" },
      "createdAt": "2026-03-01T12:00:00Z"
    },
    { ... }
  ],
  "meta": {
    "total": 1543,
    "count": 20,
    "hasMore": true,
    "nextCursor": "cursor_eyJpZCI6InBpXzAxSFhZ..."
  }
}

const refund = await cartflox.payments.refund("pi_01HXYZ789ABC");

console.log(refund.status);  // "processing"

const refund = await cartflox.payments.refund("pi_01HXYZ789ABC", {
  amount: 10000, // Rembourser 100 XOF sur 250 XOF
  reason: "requested_by_customer",
  note: "Remboursement partiel suite à réclamation client #TKT-456"
});

curl -X POST https://api.cartflox.com/v2/payments/pi_01HXYZ789ABC/refund \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "reason": "requested_by_customer" }'

{
  "success": true,
  "data": {
    "id": "ref_01HABC123",
    "paymentId": "pi_01HXYZ789ABC",
    "status": "processing",
    "amount": 10000,
    "currency": "XOF",
    "reason": "requested_by_customer",
    "createdAt": "2026-03-01T15:30:00Z"
  }
}

const transfer = await cartflox.transfers.create({
  amount: 50000,
  currency: "XOF",
  destination: {
    type: "mobile_money",
    phone: "+22507070707",
    network: "orange-money",
    name: "Kouassi Jean",
    country: "CI"
  },
  description: "Paiement fournisseur Mars 2026",
  reference: "PAY-2026-03-001" // Unique - évite les doublons
});

console.log(transfer.status); // "processing"

const transfer = await cartflox.transfers.create({
  amount: 500000,
  currency: "XOF",
  destination: {
    type: "bank_account",
    iban: "CI00XY1234567890123456789",
    name: "Société XYZ SARL",
    country: "CI"
  },
  description: "Virement salaire Mars 2026"
});

{
  "success": true,
  "data": {
    "id": "tr_01HABC456DEF",
    "status": "processing",
    "amount": 50000,
    "currency": "XOF",
    "fee": 500,
    "netAmount": 49500,
    "destination": {
      "type": "mobile_money",
      "phone": "+22507070707",
      "network": "orange-money",
      "name": "Kouassi Jean"
    },
    "estimatedArrival": "2026-03-01T13:00:00Z",
    "reference": "PAY-2026-03-001",
    "createdAt": "2026-03-01T12:00:00Z"
  }
}

const transfer = await cartflox.transfers.retrieve("tr_01HABC456DEF");
console.log(transfer.status); // processing | completed | failed

{
  "algorithmKind": "PRIORITY",
  "fallbackOrder": ["gw_paydunya_xxx", "gw_pawapay_yyy"],
  "volumeSplits": [
    { "gatewayId": "gw_paydunya_xxx", "split": 70 },
    { "gatewayId": "gw_pawapay_yyy", "split": 30 }
  ],
  "routingRules": [
    {
      "name": "Gros montants → PayDunya",
      "conditions": [
        { "field": "amount",  "operator": "gt", "value": 50000 },
        { "field": "country", "operator": "eq", "value": "CI" }
      ],
      "gatewayIds": ["gw_paydunya_xxx"]
    }
  ],
  "methodAssignments": {
    "orange_money_ci||CI": "gw_paydunya_xxx"
  },
  "allowedProviders": ["gw_paydunya_xxx", "gw_pawapay_yyy"],
  "maxRetries": 3
}

amount       — montant numérique de la transaction
currency     — code ISO de la devise (XOF, XAF, USD, …)
country      — code ISO alpha-2 (CI, SN, BJ, …)
methodCode   — code de la méthode (orange_money_ci, mtn_momo_ben, …)
methodType   — MOBILE_MONEY | CARD | BANK_TRANSFER

eq, neq          — égalité / inégalité
gt, gte, lt, lte — comparaisons numériques (ou lexicographiques pour les strings)
in               — appartenance à une liste (value: ["CI","SN","ML"])

curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer cf_live_sec_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://monsite.com/api/webhooks/cartflox" }'

curl https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer cf_live_sec_xxxx"

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const body = await req.json();

  // Structure du payload Cartflox
  const { event, data, timestamp } = body;

  switch (event) {
    case "payment.completed":
      // ✅ Mettre à jour votre base de données
      await db.orders.update({
        where: { cartfloxId: data.id },
        data: { status: "paid" }
      });
      break;

    case "payment.failed":
      await db.orders.update({
        where: { cartfloxId: data.id },
        data: { status: "failed" }
      });
      break;

    case "payment.updated":
      console.log("Statut mis à jour:", data.status);
      break;
  }

  return NextResponse.json({ received: true });
}

import express from "express";
import Cartflox from "@cartflox/node";

const app = express();
const cartflox = new Cartflox(process.env.CARTFLOX_SECRET_KEY!);

// Important: utiliser raw body parser pour les webhooks
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["cartflox-signature"] as string;

    let event;
    try {
      event = cartflox.webhooks.constructEvent(
        req.body,
        sig,
        process.env.CARTFLOX_WEBHOOK_SECRET!
      );
    } catch (err) {
      return res.status(400).send("Signature invalide");
    }

    // Traitement
    if (event.type === "payment.completed") {
      console.log("Paiement reçu:", event.data.id);
    }

    res.json({ received: true });
  }
);

{
  "event": "payment.completed",
  "data": {
    "id": "cmmtlfj27000004l4nuzy1zz5",
    "order_id": "CS-MMTLFJ1Z-B4HEE",
    "status": "SUCCESS",
    "amount": 25000,
    "currency": "XOF",
    "provider": "paydunya",
    "provider_reference": "WAVE-TXN-98765",
    "customer_name": "Kouassi Jean",
    "customer_email": "client@example.com",
    "customer_phone": "+22507070707",
    "metadata": {
      "orderId": "ORD-2026-001"
    },
    "completed_at": "2026-03-01T12:05:33Z"
  },
  "timestamp": "2026-03-01T12:05:33Z"
}

// Stocker les IDs d'événements déjà traités
const processedEvents = new Set<string>();

function handleWebhook(event: CartfloxEvent) {
  if (processedEvents.has(event.id)) {
    console.log("Événement déjà traité:", event.id);
    return;
  }
  
  processedEvents.add(event.id);
  // Traiter l'événement...
}

# Installer ngrok et exposer votre port local
ngrok http 3000

# Puis configurer l'URL ngrok comme webhookUrl
curl -X PATCH https://cartflox.com/api/v1/config/webhook \
  -H "Authorization: Bearer cf_live_sec_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://xxxx.ngrok.io/api/webhooks/cartflox" }'

cartflox-signature: t=1740823233,v1=5257a869e7ecebeda32affa62cdca3fa...

import crypto from "crypto";

function verifyWebhookSignature(
  rawBody: string,
  signature: string,
  secret: string
): boolean {
  const parts = signature.split(",");
  const timestamp = parts.find(p => p.startsWith("t="))?.split("=")[1];
  const hash      = parts.find(p => p.startsWith("v1="))?.split("=")[1];

  if (!timestamp || !hash) return false;

  // Rejeter les événements de plus de 5 minutes (replay attack)
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
  if (age > 300) return false;

  // Calculer la signature attendue
  const payload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  // Comparaison sécurisée (timing-safe)
  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(expected)
  );
}

const event = cartflox.webhooks.constructEvent(
  rawBody,     // string — corps brut de la requête
  signature,   // string — header cartflox-signature
  webhookSecret // string — votre secret de signature
);
// Lance une erreur si la signature est invalide

const MAX_AGE = 5 * 60; // 5 minutes en secondes

const timestamp = parseInt(headerParts.find(p => p.startsWith("t="))!.split("=")[1]);
if (Date.now() / 1000 - timestamp > MAX_AGE) {
  throw new Error("Webhook trop ancien — possible replay attack");
}

npm install @cartflox/node
# ou
yarn add @cartflox/node
# ou
pnpm add @cartflox/node

import Cartflox from "@cartflox/node";

export const cartflox = new Cartflox(process.env.CARTFLOX_SECRET_KEY!, {
  // Options avancées
  timeout: 30000,        // Timeout en ms (défaut: 30s)
  maxRetries: 3,         // Nombre de retries automatiques
  idempotencyKey: true,  // Générer des clés d'idempotence automatiquement
});

// Créer
const payment = await cartflox.payments.create({ ... });

// Récupérer
const payment = await cartflox.payments.retrieve("pi_01HXYZ...");

// Lister
const list = await cartflox.payments.list({ status: "completed", limit: 50 });

// Rembourser
const refund = await cartflox.payments.refund("pi_01HXYZ...", { amount: 5000 });

// Annuler (si en attente)
await cartflox.payments.cancel("pi_01HXYZ...");

// Créer un transfert
const transfer = await cartflox.transfers.create({
  amount: 50000,
  currency: "XOF",
  destination: { type: "mobile_money", phone: "+22507070707", network: "wave" }
});

// Récupérer
const transfer = await cartflox.transfers.retrieve("tr_01HABC...");

// Lister
const list = await cartflox.transfers.list({ status: "completed" });

// Vérifier et parser l'événement
const event = cartflox.webhooks.constructEvent(rawBody, signature, secret);

// Accéder aux données
console.log(event.type);    // "payment.completed"
console.log(event.data.id); // "pi_01HXYZ..."

// Types TypeScript disponibles
import type { CartfloxEvent, Payment, Transfer } from "@cartflox/node";

import Cartflox, { Payment, CreatePaymentParams } from "@cartflox/node";

const params: CreatePaymentParams = {
  amount: 5000,
  currency: "XOF",
  method: "wave",
  customer: { phone: "+22507070707" }
};

const payment: Payment = await cartflox.payments.create(params);

import { CartfloxError } from "@cartflox/node";

try {
  const payment = await cartflox.payments.create({ ... });
} catch (err) {
  if (err instanceof CartfloxError) {
    console.error("Code:", err.code);       // INSUFFICIENT_FUNDS
    console.error("Message:", err.message); // "Solde insuffisant"
    console.error("Status:", err.status);   // 400
    console.error("RequestId:", err.requestId);
  }
}

pip install cartflox-python

import os
from cartflox import Cartflox

cartflox = Cartflox(
    api_key=os.environ["CARTFLOX_SECRET_KEY"],
    timeout=30,
    max_retries=3
)

# Créer un paiement
payment = cartflox.payments.create(
    amount=25000,
    currency="XOF",
    method="wave",
    customer={
        "phone": "+22507070707",
        "email": "client@example.com",
        "name": "Kouassi Jean"
    },
    redirect_url="https://monsite.com/success",
    metadata={"order_id": "ORD-2026-001"}
)

print(payment.checkout_url)  # Rediriger le client

# Récupérer
payment = cartflox.payments.retrieve("pi_01HXYZ...")

# Lister avec filtres
payments = cartflox.payments.list(
    status="completed",
    currency="XOF",
    limit=50
)
for p in payments.data:
    print(p.id, p.amount, p.status)

# Rembourser
refund = cartflox.payments.refund(
    payment_id="pi_01HXYZ...",
    amount=5000,
    reason="requested_by_customer"
)

from fastapi import FastAPI, Request, HTTPException
from cartflox import Cartflox, WebhookVerificationError

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

@app.post("/webhook/cartflox")
async def handle_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("cartflox-signature", "")

    try:
        event = cartflox.webhooks.construct_event(
            payload=body.decode("utf-8"),
            sig_header=signature,
            secret=os.environ["CARTFLOX_WEBHOOK_SECRET"]
        )
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    if event.type == "payment.completed":
        payment = event.data
        await fulfill_order(payment.metadata["order_id"])

    return {"received": True}

from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from cartflox import Cartflox

cartflox = Cartflox(api_key=settings.CARTFLOX_SECRET_KEY)

@csrf_exempt
@require_POST
def cartflox_webhook(request):
    try:
        event = cartflox.webhooks.construct_event(
            payload=request.body.decode("utf-8"),
            sig_header=request.META.get("HTTP_CARTFLOX_SIGNATURE", ""),
            secret=settings.CARTFLOX_WEBHOOK_SECRET
        )
    except Exception:
        return JsonResponse({"error": "Invalid signature"}, status=400)

    if event.type == "payment.completed":
        Order.objects.filter(
            id=event.data.metadata["order_id"]
        ).update(status="paid")

    return JsonResponse({"received": True})

from cartflox import Cartflox, CartfloxError

try:
    payment = cartflox.payments.create(...)
except CartfloxError as e:
    print(f"Code: {e.code}")          # INSUFFICIENT_FUNDS
    print(f"Message: {e.message}")    # "Solde insuffisant"
    print(f"Status: {e.http_status}") # 400
except Exception as e:
    print(f"Erreur réseau: {e}")

composer require cartflox/cartflox-php

<?php
use Cartflox\Cartflox;

$cartflox = new Cartflox(getenv('CARTFLOX_SECRET_KEY'), [
    'timeout'     => 30,
    'max_retries' => 3,
]);

<?php
// Créer un paiement
$payment = $cartflox->payments->create([
    'amount'       => 25000,
    'currency'     => 'XOF',
    'method'       => 'wave',
    'customer'     => [
        'phone' => '+22507070707',
        'email' => 'client@example.com',
        'name'  => 'Kouassi Jean',
    ],
    'redirect_url' => 'https://monsite.com/success',
    'metadata'     => ['order_id' => 'ORD-2026-001'],
]);

// Rediriger le client
header('Location: ' . $payment->checkout_url);
exit;

// Récupérer un paiement
$payment = $cartflox->payments->retrieve('pi_01HXYZ...');

// Lister
$list = $cartflox->payments->list(['status' => 'completed', 'limit' => 20]);
foreach ($list->data as $payment) {
    echo $payment->id . ' - ' . $payment->amount . ' ' . $payment->currency . PHP_EOL;
}

// Rembourser
$refund = $cartflox->payments->refund('pi_01HXYZ...', [
    'amount' => 5000,
    'reason' => 'requested_by_customer',
]);

<?php
use Cartflox\Cartflox;
use Cartflox\Exception\WebhookSignatureException;

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

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_CARTFLOX_SIGNATURE'] ?? '';

try {
    $event = $cartflox->webhooks->constructEvent(
        $payload,
        $signature,
        getenv('CARTFLOX_WEBHOOK_SECRET')
    );
} catch (WebhookSignatureException $e) {
    http_response_code(400);
    echo json_encode(['error' => 'Signature invalide']);
    exit;
}

switch ($event->type) {
    case 'payment.completed':
        $payment = $event->data;
        // Mettre à jour la commande en base de données
        updateOrderStatus($payment->metadata['order_id'], 'paid');
        break;

    case 'payment.failed':
        notifyCustomer($event->data->customer->email);
        break;
}

http_response_code(200);
echo json_encode(['received' => true]);

<?php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Cartflox\Cartflox;

class PaymentController extends Controller
{
    private Cartflox $cartflox;

    public function __construct()
    {
        $this->cartflox = new Cartflox(config('services.cartflox.secret'));
    }

    public function create(Request $request)
    {
        $payment = $this->cartflox->payments->create([
            'amount'       => $request->amount,
            'currency'     => 'XOF',
            'method'       => $request->method ?? 'auto',
            'customer'     => ['phone' => $request->phone],
            'redirect_url' => route('payment.success'),
            'metadata'     => ['order_id' => $request->order_id],
        ]);

        return redirect($payment->checkout_url);
    }

    public function webhook(Request $request)
    {
        $event = $this->cartflox->webhooks->constructEvent(
            $request->getContent(),
            $request->header('cartflox-signature'),
            config('services.cartflox.webhook_secret')
        );

        if ($event->type === 'payment.completed') {
            // Traiter le paiement
        }

        return response()->json(['received' => true]);
    }
}

dependencies:
  cartflox_flutter: ^2.0.0

flutter pub get

<activity android:name=".MainActivity"
    android:launchMode="singleTop">
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="cartflox" android:host="callback"/>
  </intent-filter>
</activity>

import 'package:cartflox_flutter/cartflox_flutter.dart';

void main() {
  Cartflox.initialize(
    publicKey: const String.fromEnvironment('CARTFLOX_PUBLIC_KEY'),
    environment: CartfloxEnvironment.production, // ou .sandbox
  );
  runApp(const MyApp());
}

import 'package:cartflox_flutter/cartflox_flutter.dart';

class PaymentScreen extends StatelessWidget {
  Future<void> _startPayment(BuildContext context) async {
    final result = await CartfloxCheckout.present(
      context: context,
      params: PaymentParams(
        amount: 25000,
        currency: 'XOF',
        method: PaymentMethod.auto, // Affiche toutes les méthodes
        customer: Customer(
          phone: '+22507070707',
          email: 'client@example.com',
          name: 'Kouassi Jean',
        ),
        metadata: {'orderId': 'ORD-2026-001'},
      ),
    );

    switch (result.status) {
      case PaymentStatus.completed:
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text('✅ Paiement réussi !')),
        );
        // Valider la commande côté serveur via webhook
        break;
      case PaymentStatus.failed:
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('❌ Échec : ${result.errorMessage}')),
        );
        break;
      case PaymentStatus.cancelled:
        // Le client a annulé
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => _startPayment(context),
      child: const Text('Payer maintenant'),
    );
  }
}

CartfloxCheckout.present(
  context: context,
  params: PaymentParams( ... ),
  theme: CartfloxTheme(
    primaryColor: const Color(0xFF10B981),  // Votre couleur de marque
    backgroundColor: const Color(0xFF1A1A1A),
    textColor: Colors.white,
    borderRadius: 16.0,
    logoUrl: 'https://monsite.com/logo.png',
    businessName: 'Ma Boutique',
  ),
);

// 1. Votre backend crée le paiement
// POST https://votre-api.com/create-payment
// → Retourne { checkoutToken: "pi_01HXYZ...", checkoutUrl: "..." }

// 2. Le SDK Flutter utilise le token
final paymentIntent = await api.createPayment(amount: 25000);

final result = await CartfloxCheckout.presentWithToken(
  context: context,
  checkoutToken: paymentIntent.checkoutToken,
);

# Télécharger le plugin
curl -L https://downloads.cartflox.com/woocommerce/cartflox-payment-latest.zip -o cartflox-payment.zip

# Dézipper dans le dossier plugins
unzip cartflox-payment.zip -d /var/www/html/wp-content/plugins/

https://votre-boutique.com/wc-api/cartflox_webhook

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Le solde du compte est insuffisant pour effectuer cette transaction.",
    "details": {
      "field": "customer.phone",
      "value": "+22507070707"
    },
    "requestId": "req_01HXYZ123"
  }
}

import Cartflox, { CartfloxError } from "@cartflox/node";

try {
  const payment = await cartflox.payments.create({ ... });
} catch (err) {
  if (err instanceof CartfloxError) {
    switch (err.code) {
      case "INSUFFICIENT_FUNDS":
        return res.status(400).json({ message: "Solde insuffisant, veuillez recharger votre compte." });
      case "ACCOUNT_NOT_REGISTERED":
        return res.status(400).json({ message: "Ce numéro n'est pas enregistré sur ce réseau." });
      case "METHOD_NOT_AVAILABLE":
        return res.status(400).json({ message: "Cette méthode n'est pas disponible dans votre pays." });
      case "RATE_LIMIT_EXCEEDED":
        // Retry après un délai
        await sleep(1000);
        return retryPayment();
      default:
        // Erreur inattendue — logguer et afficher message générique
        logger.error("Cartflox error", { code: err.code, requestId: err.requestId });
        return res.status(500).json({ message: "Une erreur est survenue. Veuillez réessayer." });
    }
  }
  throw err; // Re-throw si ce n'est pas une erreur Cartflox
}

X-RateLimit-Limit:     120       # Limite totale par minute
X-RateLimit-Remaining: 87        # Requêtes restantes dans la fenêtre
X-RateLimit-Reset:     1740823293 # Timestamp UNIX de réinitialisation
X-RateLimit-Window:    60         # Durée de la fenêtre en secondes

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1740823293

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de débit atteinte. Veuillez attendre 23 secondes.",
    "retryAfter": 23
  }
}

async function apiCallWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.code === "RATE_LIMIT_EXCEEDED" && attempt < maxRetries) {
        const delay = (err.retryAfter ?? Math.pow(2, attempt)) * 1000;
        console.log(`Rate limit. Retry dans ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw err;
    }
  }
  throw new Error("Max retries atteint");
}

// Utilisation
const payment = await apiCallWithRetry(() =>
  cartflox.payments.create({ ... })
);

curl -X POST https://api.cartflox.com/v2/payments \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Idempotency-Key: order_ORD-2026-001_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{ ... }'