Créer un paiement

curl --request POST \
  --url https://api.example.com/v1/payments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/payments"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

payments

Créer un paiement

curl --request POST \
  --url https://api.example.com/v1/payments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/payments"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Créer un paiement

Crée une intention de paiement mobile money et retourne l’URL vers laquelle rediriger le client.

Endpoint

POST /v1/payments

Headers

Header	Requis	Description
`Authorization`	✅	`Bearer sk_xxx`
`Content-Type`	✅	`application/json`
`X-Idempotency-Key`	✅	Clé unique par paiement (128 caractères max). Absente : `400 IDEMPOTENCY_KEY_REQUIRED`

Body

Paramètre	Type	Requis	Description
`amount`	integer	✅	Montant en FCFA, entier entre 100 et 5 000 000
`currency`	string		Code ISO-4217 (défaut : `XOF`)
`payment_method`	string		`MOBILE_MONEY` (défaut). Alias accepté : `ORANGE_MONEY`. Toute autre valeur : `400`
`provider`	string		Ancien champ : `ORANGE_MONEY` ou `MOBILE_MONEY`. Toute autre valeur : `400`
`country`	string		Code ISO-2 (défaut : `ML`)
`customer_phone`	string		Numéro au format international (`+223...`)
`customer_name`	string		Nom du client
`customer_email`	string		Email du client
`customer`	object		Alternative : `{ phone, name, email }`
`description`	string		Description du paiement (renvoyée dans les webhooks)
`client_reference`	string		Votre référence de commande (120 caractères max), renvoyée dans les webhooks
`return_url`	string		URL HTTPS de votre site, hors domaines SahelPay. Le client y est renvoyé automatiquement après un paiement confirmé
`success_url` / `cancel_url`	string		URLs complémentaires conservées sur le paiement
`hosted_checkout`	boolean		`true` : `redirect_url` = checkout hébergé SahelPay. `false` (défaut API) : initiation immédiate, `redirect_url` = page de l’opérateur. Les SDKs envoient `true` par défaut
`metadata`	object		Données libres. `sahelpay_mock: true` (simulateur) ou `sandbox: true` (sandbox de l’opérateur) en test uniquement ; `marketplace` (objet, champs filtrés)
`items`	array		Partenaires SPAY : `[{ "product_id": "...", "quantity": 1 }]` (1 à 50 lignes). Obligatoire en production pour un partenaire validé ; `amount` doit égaler le total du catalogue

Les champs inconnus sont refusés (400).

Exemple

curl -X POST https://api.sahelpay.ml/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-123" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "ORANGE_MONEY",
    "country": "ML",
    "customer_phone": "+22370123456",
    "customer_name": "Amadou Diallo",
    "description": "Commande #123",
    "client_reference": "order-123",
    "return_url": "https://votre-site.com/checkout/return?order=order-123",
    "hosted_checkout": true
  }'

const payment = await sahelpay.payments.create({
  amount: 5000,
  payment_method: 'ORANGE_MONEY',
  customer_phone: '+22370123456',
  customer_name: 'Amadou Diallo',
  description: 'Commande #123',
  client_reference: 'order-123',
  return_url: 'https://votre-site.com/checkout/return?order=order-123',
  idempotency_key: 'order-123',
});

payment = client.payments.create(
    amount=5000,
    provider='ORANGE_MONEY',
    customer_phone='+22370123456',
    customer_name='Amadou Diallo',
    description='Commande #123',
    client_reference='order-123',
    return_url='https://votre-site.com/checkout/return?order=order-123',
    idempotency_key='order-123',
)

$payment = $sahelpay->payments->initiate([
    'amount' => 5000,
    'provider' => 'ORANGE_MONEY',
    'customer_phone' => '+22370123456',
    'customer_name' => 'Amadou Diallo',
    'description' => 'Commande #123',
    'client_reference' => 'order-123',
    'return_url' => 'https://votre-site.com/checkout/return?order=order-123',
    'idempotency_key' => 'order-123',
]);

Réponse

201 Created

{
  "success": true,
  "data": {
    "id": "8d6f1c2e-4b1a-4c55-9a0e-3f2b7c1d9e10",
    "status": "INITIATED",
    "payment_method": "MOBILE_MONEY",
    "country": "ML",
    "amount": 5000,
    "amount_order": 5000,
    "amount_charged": 5000,
    "currency": "XOF",
    "redirect_url": "https://app.sahelpay.ml/checkout/8d6f1c2e-4b1a-4c55-9a0e-3f2b7c1d9e10",
    "checkout_url": "https://app.sahelpay.ml/checkout/8d6f1c2e-4b1a-4c55-9a0e-3f2b7c1d9e10",
    "expires_at": null,
    "created_at": "2026-10-03T10:00:00.000Z",
    "updated_at": "2026-10-03T10:00:00.000Z"
  }
}

Avec hosted_checkout: true, le statut est INITIATED jusqu’à ce que le client ouvre le checkout.
Avec hosted_checkout: false, la réponse contient aussi provider_ref et redirect_url pointe vers la page de l’opérateur ; le statut passe à PENDING.

Statuts

Statut	Description
`INITIATED`	Créé, pas encore initié auprès de l’opérateur
`PENDING`	En attente de validation du client
`SUCCESS`	Paiement confirmé
`FAILED`	Paiement échoué
`EXPIRED`	Expiré (délai écoulé ou `POST /v1/payments/{id}/expire`)

Erreurs

HTTP	Code	Cause
`400`	`IDEMPOTENCY_KEY_REQUIRED`	Header `X-Idempotency-Key` absent
`400`	`BAD_REQUEST`	Champ invalide, provider autre que `ORANGE_MONEY`, métadonnées de test en production, moyen de paiement indisponible
`400`	`PARTNER_*`	Règles du Programme Partenaires SPAY
`401`	`PRODUCTION_KEY_DISABLED`	Clé live sans accès production
`403`	`PAID_SUBSCRIPTION_REQUIRED`	Pas d’accès production en cours
`403`	`MERCHANT_PAYMENT_DISABLED`	Le compte n’est pas autorisé à créer ce paiement
`409`	—	Même clé d’idempotence, demande différente
`429`	`RATE_LIMIT_EXCEEDED`	Plus de 10 créations par minute

Vue d'ensemble

Paiements

Liens de paiement

Paiement sécurisé

Plans

Abonnements

Portail client

Webhooks

Créer un paiement

Créer un paiement

Endpoint

Headers

Body

Exemple

Réponse

Statuts

Erreurs

​Créer un paiement

​Endpoint

​Headers

​Body

​Exemple

​Réponse

​Statuts

​Erreurs

Créer un paiement

Endpoint

Headers

Body

Exemple

Réponse

Statuts

Erreurs