Démarrage rapide

Ce guide vous mène du compte développeur au premier encaissement, dans le bac à sable : aucun argent réel n’est utilisé. Les exemples sont fournis en cURL, JavaScript (Node.js 18 ou plus), Python (bibliothèque requests) et PHP (extension cURL). Votre choix de langage est mémorisé sur toutes les pages.

Créez votre compte développeur sur le tableau de bord développeur (l’« Espace développeur ») : nom, entreprise (facultative), téléphone, e-mail et mot de passe, puis acceptez les conditions d’utilisation. Après confirmation de votre adresse e-mail, votre clé d’essai est disponible.

Rangez-la dans une variable d’environnement, jamais dans votre code :
Fenêtre de terminal
```
export SAMA_API_KEY="VOTRE_CLE_D_ESSAI"
```
Vérifiez la connexion à l’API :
Fenêtre de terminal
curl -sS https://api.sama.money/v1/health/auth \ -H "Authorization: Bearer $SAMA_API_KEY"
verifier.mjs
const response = await fetch("https://api.sama.money/v1/health/auth", { headers: { Authorization: `Bearer ${process.env.SAMA_API_KEY}` }, }); console.log(response.status, await response.json());
verifier.py
import os import requests response = requests.get( "https://api.sama.money/v1/health/auth", headers={"Authorization": f"Bearer {os.environ['SAMA_API_KEY']}"}, timeout=30, ) print(response.status_code, response.json())
verifier.php
<?php $ch = curl_init("https://api.sama.money/v1/health/auth"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SAMA_API_KEY")], ]); $body = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $body, PHP_EOL; curl_close($ch);
Réponse attendue :
```
{"status":"ok","mode":"test"}
```
Une réponse d’erreur signifie que l’en-tête Authorization est absent ou que la clé est mal copiée.

Créez un premier encaissement : vous demandez 5 000 F à un client de test. En bac à sable, l’encaissement reste en attente (pending) jusqu’à ce que le client le confirme sur son téléphone.

curl -sS -X POST https://api.sama.money/v1/charges \
  -H "Authorization: Bearer $SAMA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "client_phone": "22370000000",
    "amount_xof": 5000,
    "description": "Commande 42"
  }'

import { randomUUID } from "node:crypto";

const response = await fetch("https://api.sama.money/v1/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAMA_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ client_phone: "22370000000", amount_xof: 5000, description: "Commande 42" }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error?.code} (requête ${data.error?.request_id})`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://api.sama.money/v1/charges",
    headers={
        "Authorization": f"Bearer {os.environ['SAMA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"client_phone": "22370000000", "amount_xof": 5000, "description": "Commande 42"},
    timeout=30,
)
data = response.json()
if not response.ok:
    raise SystemExit(f"{data['error']['code']} (requête {data['error']['request_id']})")
print(data)

<?php
function uuid_v4(): string {
    $b = random_bytes(16);
    $b[6] = chr((ord($b[6]) & 0x0f) | 0x40);
    $b[8] = chr((ord($b[8]) & 0x3f) | 0x80);
    return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($b), 4));
}

$ch = curl_init("https://api.sama.money/v1/charges");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SAMA_API_KEY"),
        "Idempotency-Key: " . uuid_v4(),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "client_phone" => "22370000000",
        "amount_xof" => 5000,
        "description" => "Commande 42",
    ]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $body, PHP_EOL;

L’API répond 200 avec l’encaissement en attente :

{
  "reference": "chg_8f3a1c9e2b7d4e60a1c3",
  "object": "charge",
  "mode": "test",
  "amount_xof": 5000,
  "currency": "XOF",
  "client_phone": "22370000000",
  "status": "pending",
  "description": "Commande 42",
  "partner_reference": null,
  "account": null,
  "error_message": null,
  "created": 1790848800
}

Conservez la reference : elle identifie l’encaissement dans GET /v1/charges/{reference}. D’autres champs peuvent s’ajouter à la réponse : ignorez ceux que vous ne connaissez pas.

Pour la suite (enregistrer l’adresse de réception de vos notifications, simuler en bac à sable la confirmation du client, relire l’état d’un encaissement), voir la Référence, réservée aux développeurs inscrits. Pour passer en production : Comptes et vérification.

Trois règles à retenir

Idempotence : envoyez un en-tête Idempotency-Key (un UUID par opération) sur toute opération monétaire. Rejouer la même requête avec la même clé renvoie le même résultat.
Montants : des entiers en francs CFA (amount_xof), sans décimale.
Asynchrone : le client confirme, pas vous. N’expédiez jamais une commande pour une demande encore pending : attendez la notification ou relisez GET /v1/charges/{reference}.

Suite

Encaisser un paiement : le parcours complet, cas d’échec compris.