Envoyer de l'argent

Les transferts font sortir de l’argent : vous envoyez une somme vers le compte Mobile Money d’un fournisseur, d’un salarié ou d’un client à rembourser. Cartflox confie l’envoi à l’une de vos passerelles qui sait le faire, avec vos propres clés. Les espaces gérés par nyole (argent tenu par Cartflox) n’ont pas accès aux transferts pour le moment.

Ouvert à tous les espaces

Les transferts utilisent les mêmes passerelles que l’encaissement : dès qu’une de vos passerelles sait envoyer de l’argent (PawaPay, PayDunya, Hub2, Notch Pay, Monetbil, Flutterwave, Paystack, FedaPay, FeexPay), vous pouvez envoyer, avec les clés déjà saisies. Dans votre tableau de bord, la rubrique Transferts d’argent a deux réglages : Passerelles (celles que Cartflox peut utiliser, et ce qui leur manque) et Méthodes (les opérateurs autorisés, pays par pays). L’administration Cartflox peut fermer les transferts d’un espace ; l’API répond alors 403 avec le code transferts_inactifs.

POST/v1/transfersEnvoyer une somme vers un compte Mobile Money

Paramètres

Paramètre	Type	Requis	Description
amount	number	Oui	Montant reçu par le bénéficiaire, entier pour les francs (5000 pour 5 000 XOF)
country	string	Oui	Pays du bénéficiaire, ISO 3166-1 alpha-2 : CI, SN, BJ, BF, TG, ML, NE, GN, CM, GA, CG, CD, GH, NG, KE, TZ, UG, RW, ZM
operator	string	Oui	Opérateur du bénéficiaire : orange_money, mtn_money, moov_money, wave, free_money, tmoney, mpesa, airtel_money… Les alias courants (mtn, orange, MTN_MOMO_CIV) sont acceptés.
phone	string	Oui	Numéro du bénéficiaire, tel qu’on le compose dans le pays (0712345678) ou en international (+2250712345678)
currency	string	Non	Devise, déduite du pays (XOF, XAF, GHS, KES…). Une devise qui ne correspond pas au pays est refusée.
recipient_name	string	Non	Nom du bénéficiaire, pour vos relevés et pour le fournisseur
description	string	Non	Motif, transmis quand l’opérateur l’affiche au bénéficiaire
idempotency_key	string	Non	Même rôle que l’en-tête Idempotency-Key ci-dessous
metadata	object	Non	Vos données libres, conservées avec le transfert

En-têtes

En-tête	Valeur
Authorization	Bearer af_live_sec_... (ou x-api-key). La clé secrète uniquement : la clé publique du widget est refusée, elle ne peut pas faire sortir d’argent.
Content-Type	application/json
Idempotency-Key	Fortement conseillé. Une chaîne unique par transfert (numéro de facture, identifiant de paie…) : si le même appel est rejoué, le transfert existant est renvoyé (HTTP 200, en-tête Idempotent-Replayed: true) au lieu d’envoyer une seconde fois l’argent.

Exemples

curl

curl -X POST https://cartflox.com/api/v1/transfers \
  -H "Authorization: Bearer af_live_sec_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: salaire-2026-09-awa" \
  -d '{
    "amount": 50000,
    "country": "CI",
    "operator": "orange_money",
    "phone": "0712345678",
    "recipient_name": "Awa Koné",
    "description": "Salaire septembre"
  }'

Node.js

const res = await fetch("https://cartflox.com/api/v1/transfers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CARTFLOX_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "salaire-2026-09-awa",
  },
  body: JSON.stringify({
    amount: 50000,
    country: "CI",
    operator: "orange_money",
    phone: "0712345678",
    recipient_name: "Awa Koné",
    description: "Salaire septembre",
  }),
});
const transfert = await res.json();
console.log(transfert.status); // "processing" le plus souvent, "succeeded" ou "failed"

PHP

$ch = curl_init("https://cartflox.com/api/v1/transfers");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CARTFLOX_SECRET_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: salaire-2026-09-awa",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 50000,
    "country" => "CI",
    "operator" => "orange_money",
    "phone" => "0712345678",
    "recipient_name" => "Awa Koné",
    "description" => "Salaire septembre",
  ]),
]);
$transfert = json_decode(curl_exec($ch), true);
echo $transfert["status"];

Python

import os, requests

res = requests.post(
    "https://cartflox.com/api/v1/transfers",
    headers={
        "Authorization": f"Bearer {os.environ['CARTFLOX_SECRET_KEY']}",
        "Idempotency-Key": "salaire-2026-09-awa",
    },
    json={
        "amount": 50000,
        "country": "CI",
        "operator": "orange_money",
        "phone": "0712345678",
        "recipient_name": "Awa Koné",
        "description": "Salaire septembre",
    },
)
print(res.json()["status"])

Réponse

{
  "id": "cmfx1a2b3c4d5e6f7g8h9i0j",
  "reference": "ddf9f0bf-f310-4126-83d9-dc8bc92b6e79",
  "status": "processing",
  "amount": 50000,
  "currency": "XOF",
  "fee": 0,
  "country": "CI",
  "operator": "orange_money",
  "provider_operator": "ORANGE_CIV",
  "phone": "2250712345678",
  "recipient_name": "Awa Koné",
  "description": "Salaire septembre",
  "provider": "PawaPay",
  "provider_reference": null,
  "failure": null,
  "idempotency_key": "salaire-2026-09-awa",
  "created": "2026-09-18T09:12:41.000Z",
  "completed": null
}

Statut	Sens
pending	Créé, pas encore confié au fournisseur
processing	Confié au fournisseur, l’opérateur traite l’envoi. C’est le cas le plus fréquent juste après l’appel.
succeeded	L’argent est arrivé sur le compte du bénéficiaire. completed porte la date.
failed	Refusé par l’opérateur ou le fournisseur. failure.code et failure.message disent pourquoi. Rien n’a été débité.

fee vaut 0 : Cartflox ne prélève rien sur un transfert, c’est votre agrégateur qui applique ses frais sur son portefeuille.

Suivre un transfert

Le statut évolue après l’appel. Deux façons de le suivre, à utiliser ensemble :

GET/v1/transfers/{id}Un transfert, par identifiant Cartflox ou par référence

GET/v1/transfers?status=processing&limit=50Vos derniers transferts, filtrables par statut

Et les webhooks transfer.succeeded et transfer.failed, envoyés à l’adresse configurée pour vos paiements, signés de la même manière, avec le transfert complet dans data. Voir les événements.

Pays et opérateurs de votre espace

Les opérateurs disponibles dépendent des passerelles que vous avez branchées. Pour les connaître sans deviner :

GET/v1/transfers?options=1Pays, devises et opérateurs ouverts à cet espace

{
  "countries": [
    { "code": "CI", "name": "Côte d'Ivoire", "currency": "XOF",
      "operators": [
        { "code": "orange_money", "name": "Orange Money", "provider": "PawaPay" },
        { "code": "mtn_money", "name": "MTN Mobile Money", "provider": "PawaPay" },
        { "code": "moov_money", "name": "Moov Money", "provider": "PawaPay" },
        { "code": "wave", "name": "Wave", "provider": "PawaPay" }
      ] }
  ]
}

D'où part l'argent

L’argent part du portefeuille de votre agrégateur (PawaPay, PayDunya, Hub2, Notch Pay, Monetbil, Flutterwave, Paystack, FedaPay ou FeexPay), qui le débite avec ses propres frais et à ses propres conditions (portefeuille de décaissement approvisionné, adresse IP autorisée chez certains).

Erreurs

HTTP	code	Sens
401	unauthorized	Clé absente, invalide, ou clé publique
403	transferts_inactifs	Les transferts ne sont pas ouverts sur cet espace
403	connect_non_disponible	Les espaces gérés par nyole n’ont pas accès aux transferts
400	pays_non_desservi	Pays hors de la liste
400	operateur_non_desservi	Aucune de vos passerelles ne sait envoyer vers cet opérateur dans ce pays
400	methode_desactivee	Vous avez coupé cet opérateur dans vos méthodes de transfert
400	telephone_invalide	Le numéro n’est pas un numéro possible de ce pays
400	devise_invalide	La devise ne correspond pas au pays
400	montant_invalide	Montant nul ou négatif
429	plafond_journalier	Le nombre de transferts par jour de l’espace est atteint
429	rate_limited	Plus de 30 appels par minute