API publique de collecte de paiement

Documentation d'integration SOLIMI pour marchands, fintechs et banques

Ce guide explique comment connecter votre application a l'API publique SOLIMI pour initier des paiements, consulter leur statut, lire votre solde, recuperer les moyens de paiement disponibles et recevoir les notifications webhook.

REST JSON HMAC-SHA256 Idempotence Webhooks securises

Telecharger la collection Postman Telecharger l'environnement sandbox

Authentification Chaque requete est signee avec votre cle secrete API.

Devise Les transactions de collecte sont exprimees en XOF.

Canaux Mobile money, compte SOLIMI et carte SOLIMI.

Environnements et pre-requis

Avant l'integration, l'equipe SOLIMI vous fournit un compte partenaire, une cle API, un secret API et configure les adresses IP autorisees. Le secret API est affiche une seule fois: conservez-le dans un coffre de secrets.

Environnement	Base URL	Usage
Local developpement	`http://localhost:8000`	Tests internes SOLIMI ou recette locale.
Sandbox	`https://sandbox-api.solimi.co`	Integration partenaire avant mise en production.
Production	`https://api.solimi.co`	Transactions reelles apres validation SOLIMI.

Les domaines sandbox et production ci-dessus sont les URLs de reference a confirmer avec SOLIMI lors de l'onboarding. Ne partagez jamais votre secret API dans un frontend, une application mobile ou un depot Git.

Authentification HMAC

Toutes les routes publiques securisees utilisent une signature HMAC SHA-256. SOLIMI verifie votre cle API, l'adresse IP source, l'horodatage et la signature calculee a partir du corps exact de la requete.

Headers obligatoires

Header	Description
`x-api-key`	Votre cle API publique, par exemple `sk_test_...` ou `sk_live_...`.
`x-timestamp`	Timestamp Unix en secondes. La tolerance est de 300 secondes.
`x-signature`	HMAC SHA-256 hexadecimal du message `raw_body + timestamp`.
`Idempotency-Key`	Obligatoire pour `POST /v1/payments/request`. Doit etre unique par tentative logique.

Algorithme

message = raw_request_body + x_timestamp
x_signature = HMAC_SHA256_HEX(api_secret, message)

Pour une requete GET, le corps est vide. Le message signe est donc uniquement le timestamp.

Paiements

Une demande de paiement cree une intention de collecte. Selon le type de paiement, le client approuve le paiement sur mobile money, via son compte SOLIMI ou via une carte SOLIMI.

Mobile money

payment_type = mobile_money

Requiert provider: mixx, coris_money ou moov_money.

Compte SOLIMI

payment_type = solimi_account

Requiert account_id sur 12 chiffres.

Carte SOLIMI

payment_type = solimi_card

Requiert card_id sur 8 chiffres.

Cycle de vie

Statut	Signification
`INITIATED`	La demande de paiement est creee.
`PENDING_APPROVAL`	Le paiement attend l'approbation du client.
`APPROVED`	Le client a approuve le paiement.
`PROCESSING`	Le traitement est en cours.
`SUCCESS`	Le paiement est reussi.
`FAILED`	Le paiement a echoue.
`DECLINED`	Le client ou le systeme a refuse le paiement.
`EXPIRED`	La demande a expire.
`CANCELLED`	La demande a ete annulee.

Reference des payloads et validations

Cette section precise le role de chaque champ, son type, son caractere obligatoire, sa taille et le format attendu. Les regex ci-dessous sont les validations recommandees cote integrateur, afin de detecter les erreurs avant l'appel API.

SOLIMI valide strictement les payloads. Si un champ optionnel n'est pas applicable au type de paiement, ne l'envoyez pas. Exemple: n'envoyez pas account_id pour un paiement mobile_money.

Headers de securite

Champ	Role	Type	Obligatoire	Taille	Regex / Format	Exemple
`x-api-key`	Identifie la cle API du partenaire.	string	Oui	Variable	`^sk_(test\|live)_[A-Za-z0-9]+$`	`sk_test_abcd...`
`x-timestamp`	Protege contre le rejeu de requetes.	string numeric	Oui	10 chiffres en secondes	`^\d{10}$`, Unix timestamp, tolerance 300s	`1781899200`
`x-signature`	Prouve que la requete vient du serveur partenaire.	string	Oui	64 caracteres	`^[a-f0-9]{64}$`	`7d9f...a31c`
`Idempotency-Key`	Evite la creation de doublons lors des retries.	string	Oui pour creation paiement	Recommande: 1 a 100	`^[A-Za-z0-9._:-]{1,100}$`	`ORDER-2026-0001`

`PaymentRequestCreate` - Creation d'un paiement

Champ	Role metier	Type	Obligatoire	Taille	Regex / Valeurs	Notes
`merchant_reference`	Reference unique de la transaction dans le systeme du marchand.	string	Oui	1 a 100 caracteres	`^[A-Za-z0-9._:-]{1,100}$` recommande	Utilisez la meme valeur comme base de `Idempotency-Key`.
`payment_type`	Canal de paiement a utiliser.	enum string	Oui	Variable	`mobile_money`, `solimi_account`, `solimi_card`	Determine les champs conditionnels requis.
`amount`	Montant a collecter.	integer	Oui	Nombre entier positif	`^[1-9]\d*$`	Montant en XOF, sans decimales.
`currency`	Devise de la transaction.	literal string	Non	3 caracteres	`^XOF$`	Facultatif. Si absent, le backend applique `XOF`.
`description`	Libelle visible pour reconciliation ou support.	string	Oui	Minimum 1 caractere	`^.{1,}$`	Recommande: inclure le numero de commande.
`customer_phone`	Numero du client payeur.	string	Oui	8 a 20 caracteres	`^\+?[0-9]{8,20}$` recommande	Envoyez le numero au format international quand possible.
`provider`	Operateur mobile money a utiliser.	enum string	Oui si `mobile_money`	Variable	`mixx`, `coris_money`, `moov_money`	Ne pas envoyer pour `solimi_account` ou `solimi_card`.
`account_id`	Identifiant du compte SOLIMI client.	string	Oui si `solimi_account`	Exactement 12 chiffres	`^\d{12}$`	Refuse si la longueur est differente de 12.
`card_id`	Identifiant de la carte SOLIMI client.	string	Oui si `solimi_card`	Exactement 8 chiffres	`^\d{8}$`	Refuse si la longueur est differente de 8.

Regles conditionnelles par type de paiement

`payment_type`	Champ requis	Champs a ne pas envoyer	Exemple minimal
`mobile_money`	`provider`	`account_id`, `card_id`	`{"payment_type":"mobile_money","provider":"mixx"}`
`solimi_account`	`account_id`	`provider`, `card_id`	`{"payment_type":"solimi_account","account_id":"1234567890"}`
`solimi_card`	`card_id`	`provider`, `account_id`	`{"payment_type":"solimi_card","card_id":"12345678"}`

`PaymentRequestResponse` - Reponse de creation

Champ	Role	Type	Format / Valeurs
`reference`	Reference SOLIMI du paiement.	string	`PAY-...`, a conserver pour le suivi.
`merchant_reference`	Reference marchand transmise dans la requete.	string	1 a 100 caracteres.
`payment_type`	Type de paiement retenu.	enum	`mobile_money`, `solimi_account`, `solimi_card`.
`provider`	Operateur mobile money.	enum ou null	`mixx`, `coris_money`, `moov_money`, ou `null`.
`amount`	Montant demande.	integer	Entier positif.
`currency`	Devise.	string	`XOF`.
`description`	Libelle de la demande.	string	Texte non vide.
`customer_phone`	Numero client.	string	8 a 20 caracteres.
`status`	Etat initial ou courant.	enum	Voir la table des statuts.
`expires_at`	Date d'expiration de la demande.	datetime	ISO 8601, UTC recommande.
`created_at`	Date de creation.	datetime	ISO 8601.

`PaymentStatusResponse` - Suivi de paiement

Champ	Role	Type	Format / Valeurs
`reference`	Reference SOLIMI a interroger.	string	`PAY-...`.
`merchant_reference`	Reference du marchand.	string	1 a 100 caracteres.
`partner_id`	Identifiant technique du partenaire.	UUID	`^[0-9a-fA-F-]{36}$`.
`payment_type`	Canal utilise.	enum	Types de paiement supportes.
`provider`	Provider mobile money.	enum ou null	Null hors mobile money.
`amount`	Montant.	integer	Entier positif.
`currency`	Devise.	string	`XOF`.
`status`	Etat courant.	enum	`INITIATED`, `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `SUCCESS`, `FAILED`, `DECLINED`, `EXPIRED`, `CANCELLED`.
`failure_reason`	Cause d'echec si disponible.	string ou null	Renseigne principalement les statuts non reussis.
`expires_at`	Expiration.	datetime	ISO 8601.
`approved_at`	Date d'approbation client.	datetime ou null	ISO 8601.
`completed_at`	Date de succes final.	datetime ou null	ISO 8601.
`failed_at`	Date d'echec.	datetime ou null	ISO 8601.
`declined_at`	Date de refus.	datetime ou null	ISO 8601.

Payloads webhook

Champ	Role	Type	Obligatoire	Format / Regex
`url`	Endpoint HTTPS du partenaire.	URL	Oui a la creation	`^https://.+` recommande en production.
`secret`	Secret partage avec SOLIMI pour authentifier les webhooks recus.	string	Non	Minimum 16 caracteres. Recommande: 32+ caracteres aleatoires.
`is_active`	Active ou desactive la reception.	boolean	Non, uniquement update	`true` ou `false`.

Endpoints publics

Les endpoints ci-dessous sont accessibles sous le prefixe /v1.

GET/v1/health

Public

Verifie la disponibilite de l'API.

Headers

Header	Obligatoire	Valeur
`content-type`	Non	`application/json`

Payload

Aucun body requis.

Reponses possibles

HTTP	Cas	Corps
`200`	API disponible	`{"status":"ok","service":"solimi-payment-api"}`
`5xx`	Service indisponible	Erreur serveur ou timeout infrastructure.

Exemples d'appel

cURL

curl -X GET "{{base_url}}/v1/health"

PHP

<?php
echo file_get_contents("{{base_url}}/v1/health");

Node.js

const response = await fetch("{{base_url}}/v1/health");
console.log(await response.json());

Python

import requests

response = requests.get("{{base_url}}/v1/health")
print(response.json())

Exemple de reponse 200

{
  "status": "ok",
  "service": "solimi-payment-api"
}

POST/v1/payments/request

HMAC + Idempotency-Key

Cree une demande de paiement.

Headers obligatoires

Header	Role	Format / valeur
`content-type`	Format du body.	`application/json`
`x-api-key`	Identifie le partenaire.	Cle API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes, tolerance 300s.
`x-signature`	Authentifie la requete.	HMAC SHA-256 hex de `raw_body + timestamp`.
`Idempotency-Key`	Evite les doublons lors des retries.	Unique par tentative logique, ex: `ORDER-2026-0001`.

Payload et validations

Champ	Type	Obligatoire	Valeurs / regex	Role
`merchant_reference`	string	Oui	1-100, `^[A-Za-z0-9._:-]{1,100}$`	Reference unique cote marchand.
`payment_type`	enum	Oui	`mobile_money`, `solimi_account`, `solimi_card`	Canal de collecte.
`provider`	enum/null	Oui si mobile money	`mixx`, `moov_money`, `coris_money`	Operateur mobile money.
`amount`	integer	Oui	`^[1-9]\d*$`	Montant XOF sans decimales.
`currency`	string	Non	`XOF`	Facultatif. Devise par defaut appliquee par le backend.
`description`	string	Oui	Non vide	Libelle/reconciliation.
`customer_phone`	string	Oui	`^\+?[0-9]{8,20}$`	Numero du client payeur.
`account_id`	string/null	Oui si compte SOLIMI	`^\d{12}$`	Compte SOLIMI du client.
`card_id`	string/null	Oui si carte SOLIMI	`^\d{8}$`	Carte SOLIMI du client.

Exemple de payload

{
  "merchant_reference": "ORDER-2026-0001",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "description": "Commande ORDER-2026-0001",
  "customer_phone": "22890112233"
}

Reponses possibles

HTTP	Code applicatif	Cas
`201`	-	Demande de paiement creee.
`400`	`domain_error`	Regle metier invalide.
`401`	`authentication_failed`	Headers HMAC manquants ou invalides.
`403`	`authorization_failed`	IP non autorisee, partenaire inactif ou credentials invalides.
`409`	`idempotency_conflict` / `duplicate_merchant_reference`	Cle idempotente reutilisee avec un payload different ou reference marchand deja utilisee.
`422`	`validation_error`	Champ manquant ou format invalide.
`500`	`payment_core_sync_failed`	Erreur de synchronisation interne avec le noyau SOLIMI.

Exemples d'appel

cURL

BODY='{"merchant_reference":"ORDER-2026-0001","payment_type":"mobile_money","provider":"mixx","amount":25000,"description":"Commande ORDER-2026-0001","customer_phone":"22890112233"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s%s" "$BODY" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')

curl -X POST "{{base_url}}/v1/payments/request" \
  -H "content-type: application/json" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -H "Idempotency-Key: ORDER-2026-0001" \
  -d "$BODY"

PHP

<?php
$apiKey = getenv("SOLIMI_API_KEY");
$apiSecret = getenv("SOLIMI_API_SECRET");
$timestamp = (string) time();
$body = json_encode([
  "merchant_reference" => "ORDER-2026-0001",
  "payment_type" => "mobile_money",
  "provider" => "mixx",
  "amount" => 25000,
  "description" => "Commande ORDER-2026-0001",
  "customer_phone" => "22890112233"
], JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", $body . $timestamp, $apiSecret);

$ch = curl_init("{{base_url}}/v1/payments/request");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_HTTPHEADER => [
    "content-type: application/json",
    "x-api-key: $apiKey",
    "x-timestamp: $timestamp",
    "x-signature: $signature",
    "Idempotency-Key: ORDER-2026-0001"
  ]
]);
echo curl_exec($ch);

Node.js

import crypto from "node:crypto";

const body = JSON.stringify({
  merchant_reference: "ORDER-2026-0001",
  payment_type: "mobile_money",
  provider: "mixx",
  amount: 25000,
  description: "Commande ORDER-2026-0001",
  customer_phone: "22890112233"
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(body + timestamp).digest("hex");

const response = await fetch("{{base_url}}/v1/payments/request", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.SOLIMI_API_KEY,
    "x-timestamp": timestamp,
    "x-signature": signature,
    "Idempotency-Key": "ORDER-2026-0001"
  },
  body
});
console.log(await response.json());

Python

import hashlib
import hmac
import json
import os
import time
import requests

payload = {
    "merchant_reference": "ORDER-2026-0001",
    "payment_type": "mobile_money",
    "provider": "mixx",
    "amount": 25000,
    "description": "Commande ORDER-2026-0001",
    "customer_phone": "22890112233",
}
body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), (body + timestamp).encode(), hashlib.sha256).hexdigest()

response = requests.post(
    "{{base_url}}/v1/payments/request",
    data=body.encode(),
    headers={
        "content-type": "application/json",
        "x-api-key": os.environ["SOLIMI_API_KEY"],
        "x-timestamp": timestamp,
        "x-signature": signature,
        "Idempotency-Key": "ORDER-2026-0001",
    },
)
print(response.json())

Exemple de reponse 201

{
  "reference": "PAY-8C7F36A1B2",
  "merchant_reference": "ORDER-2026-0001",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "description": "Commande ORDER-2026-0001",
  "customer_phone": "22890112233",
  "status": "PENDING_APPROVAL",
  "expires_at": "2026-06-19T21:00:00Z",
  "created_at": "2026-06-19T20:45:00Z"
}

GET/v1/payments/status/{reference}

HMAC

Retourne l'etat courant d'un paiement.

Headers obligatoires

Header	Role	Format / valeur
`x-api-key`	Identifie le partenaire.	Cle API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes.
`x-signature`	Authentifie la requete GET.	HMAC SHA-256 hex du `timestamp`.

Parametres

Parametre	Type	Obligatoire	Format	Role
`reference`	path string	Oui	`PAY-...` ou `SOLPAY...`	Reference SOLIMI retournee a la creation.

Reponses possibles

HTTP	Code applicatif	Cas
`200`	-	Statut retourne.
`401`	`authentication_failed`	Signature invalide.
`403`	`authorization_failed`	Partenaire non autorise.
`404`	`not_found`	Reference inconnue pour ce partenaire.

Exemples d'appel

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/payments/status/PAY-8C7F36A1B2" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/payments/status/PAY-8C7F36A1B2", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/payments/status/PAY-8C7F36A1B2", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/payments/status/PAY-8C7F36A1B2",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

Exemple de reponse 200

{
  "reference": "PAY-8C7F36A1B2",
  "merchant_reference": "ORDER-2026-0001",
  "partner_id": "945adbc3-1e63-46da-8128-8ef790b50714",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "status": "SUCCESS",
  "failure_reason": null,
  "expires_at": "2026-06-19T21:00:00Z",
  "approved_at": "2026-06-19T20:46:11Z",
  "completed_at": "2026-06-19T20:46:18Z",
  "failed_at": null,
  "declined_at": null
}

GET/v1/account/balance

HMAC

Retourne le solde disponible et le solde reserve du partenaire.

Headers obligatoires

Header	Role	Format / valeur
`x-api-key`	Identifie le partenaire.	Cle API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes.
`x-signature`	Authentifie la requete GET.	HMAC SHA-256 hex du `timestamp`.

Payload

Aucun body requis.

Reponses possibles

HTTP	Code applicatif	Cas
`200`	-	Solde retourne.
`401`	`authentication_failed`	Signature invalide.
`403`	`authorization_failed`	Partenaire non autorise.

Exemples d'appel

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/account/balance" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/account/balance", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/account/balance", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/account/balance",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

Exemple de reponse 200

{
  "partner_reference": "PART-637C64AC5B75",
  "currency": "XOF",
  "available_balance": 1250000,
  "reserved_balance": 50000,
  "environment": "sandbox"
}

GET/v1/payment-methods

HMAC

Liste les moyens de paiement actifs.

Headers obligatoires

Header	Role	Format / valeur
`x-api-key`	Identifie le partenaire.	Cle API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes.
`x-signature`	Authentifie la requete GET.	HMAC SHA-256 hex du `timestamp`.

Payload

Aucun body requis.

Champs de reponse

Champ	Type	Valeurs possibles	Role
`code`	string	`mixx`, `moov_money`, `solimi_account`	Code technique a envoyer dans `provider` si applicable.
`name`	string	Libelle humain	Nom affichable.
`provider`	string/null	Provider mobile money ou null	Operateur associe.
`is_active`	boolean	`true`/`false`	Disponibilite du moyen.

Reponses possibles

HTTP	Code applicatif	Cas
`200`	-	Liste retournee.
`401`	`authentication_failed`	Signature invalide.
`403`	`authorization_failed`	Partenaire non autorise.

Exemples d'appel

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/payment-methods" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/payment-methods", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/payment-methods", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/payment-methods",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

Exemple de reponse 200

[
  {
    "code": "mixx",
    "name": "Mixx by Yas",
    "provider": "mixx",
    "is_active": true
  },
  {
    "code": "moov_money",
    "name": "Moov Money",
    "provider": "moov_money",
    "is_active": true
  }
]

L'URL webhook du partenaire est configuree par l'equipe SOLIMI dans la plateforme interne. Il n'existe plus d'endpoint public permettant au partenaire de creer ou modifier lui-meme son webhook.

Collection Postman

La collection Postman SOLIMI regroupe les requetes pretes a tester pour les endpoints publics: creation de paiement, consultation de statut, solde du partenaire et moyens de paiement disponibles. Elle aide les equipes techniques a demarrer rapidement sans reconstruire les headers et payloads depuis zero.

Comment l'utiliser

Telechargez le fichier JSON de collection.
Dans Postman, cliquez sur Import, puis selectionnez le fichier telecharge.
Renseignez les variables base_url, api_key, api_secret et les valeurs de test.
Lancez les requetes de la section 03 - Payments pour valider l'integration.

Fichier disponible

Format JSON compatible avec Postman. Le fichier contient les scripts necessaires pour calculer les headers HMAC et ajouter automatiquement l'idempotency key sur les paiements.

Telecharger la collection Postman

La collection ne contient pas vos secrets. Les valeurs sensibles doivent etre renseignees dans vos variables d'environnement Postman et ne doivent pas etre partagees publiquement.

Webhooks

SOLIMI appelle votre endpoint webhook lorsqu'un paiement change d'etat. Votre serveur doit repondre avec un statut HTTP 2xx. En cas d'echec, SOLIMI relance selon les delais: 30s, 60s, 300s, 900s.

Header SOLIMI	Description
`x-solimi-signature`	Secret webhook partage avec SOLIMI. Comparez cette valeur au secret configure.
`x-solimi-timestamp`	Timestamp Unix en secondes, utile pour refuser les notifications trop anciennes.
`x-solimi-event`	Nom de l'evenement, par exemple `payment.success`.

Evenements

payment.initiated, payment.pending_approval, payment.success, payment.failed, payment.declined, payment.expired.

Verification webhook FastAPI

import time

from fastapi import APIRouter, Header, HTTPException, Request

router = APIRouter()

SOLIMI_WEBHOOK_SECRET = "secret_fourni_par_solimi"
SIGNATURE_TOLERANCE_SECONDS = 300


@router.post("/webhooks/solimi/payments")
async def solimi_payment_webhook(
    request: Request,
    x_solimi_signature: str = Header(...),
    x_solimi_timestamp: str = Header(...),
    x_solimi_event: str = Header(...),
):
    if x_solimi_signature != SOLIMI_WEBHOOK_SECRET:
        raise HTTPException(status_code=401, detail="Invalid webhook signature")

    try:
        timestamp = int(x_solimi_timestamp)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid timestamp")

    if abs(int(time.time()) - timestamp) > SIGNATURE_TOLERANCE_SECONDS:
        raise HTTPException(status_code=400, detail="Expired webhook timestamp")

    payload = await request.json()
    payment = payload.get("payment", {})

    # Mettre a jour la commande/facture du partenaire ici.
    # Exemple: payment.success => commande payee.

    return {
        "received": True,
        "event": x_solimi_event,
        "merchant_reference": payment.get("merchant_reference"),
        "solimi_reference": payment.get("reference"),
        "status": payment.get("status"),
    }

La verification est volontairement simple: le header x-solimi-signature contient directement le secret webhook. Gardez ce secret cote serveur uniquement.

Erreurs

Les erreurs sont retournees au format JSON suivant.

{
  "code": "authentication_failed",
  "message": "Missing authentication headers",
  "details": null
}

HTTP	Code	Action recommandee
401	`authentication_failed`	Verifier les headers HMAC, le timestamp et la signature.
403	`authorization_failed`	Verifier l'IP autorisee, l'etat de la cle API et du partenaire.
404	`not_found`	Verifier la reference de paiement ou la route appelee.
409	`idempotency_conflict`	Reutiliser une meme cle uniquement pour la meme requete logique.
422	`validation_error`	Corriger les champs invalides dans le payload.

Checklist de mise en production

Stocker la cle API et le secret API dans un coffre de secrets cote serveur.
Signer toutes les requetes avec le corps exact envoye a SOLIMI.
Utiliser une cle d'idempotence unique pour chaque paiement marchand.
Verifier les webhooks en comparant x-solimi-signature au secret webhook configure.
Prevoir le polling de statut en secours si un webhook est indisponible.
Fournir a SOLIMI les adresses IP publiques de vos serveurs.
Tester les cas succes, echec, refus, expiration et retry webhook en sandbox.

Public payment collection API

SOLIMI integration documentation for merchants, fintechs and banks

This guide explains how to connect your application to the SOLIMI public API to initiate payments, check status, read your balance, list available payment methods and receive signed webhook notifications.

REST JSON HMAC-SHA256 Idempotency Secured webhooks

Download Postman collection Download sandbox environment

Authentication Every request is signed with your API secret.

Currency Collection transactions are expressed in XOF.

Channels Mobile money, SOLIMI account and SOLIMI card.

Environments and requirements

Before integrating, SOLIMI provides a partner account, an API key, an API secret and configures your allowed IP addresses. The API secret is shown once: store it in a secure secrets manager.

Environment	Base URL	Usage
Local development	`http://localhost:8000`	Internal SOLIMI testing or local acceptance.
Sandbox	`https://sandbox-api.solimi.co`	Partner integration before production activation.
Production	`https://api.solimi.co`	Live transactions after SOLIMI approval.

The sandbox and production domains above are reference URLs to confirm with SOLIMI during onboarding. Never expose your API secret in a frontend, a mobile app or a Git repository.

HMAC authentication

All secured public routes use an HMAC SHA-256 signature. SOLIMI validates your API key, source IP address, timestamp and signature computed from the exact raw request body.

Required headers

Header	Description
`x-api-key`	Your public API key, for example `sk_test_...` or `sk_live_...`.
`x-timestamp`	Unix timestamp in seconds. Allowed tolerance is 300 seconds.
`x-signature`	Hexadecimal HMAC SHA-256 of `raw_body + timestamp`.
`Idempotency-Key`	Required for `POST /v1/payments/request`. Must be unique per logical attempt.

Algorithm

message = raw_request_body + x_timestamp
x_signature = HMAC_SHA256_HEX(api_secret, message)

For a GET request, the body is empty, so the signed message is only the timestamp.

Payments

A payment request creates a collection intent. Depending on the payment type, the customer approves it via mobile money, a SOLIMI account or a SOLIMI card.

Mobile money

payment_type = mobile_money

Requires provider: mixx, coris_money or moov_money.

SOLIMI account

payment_type = solimi_account

Requires a 10-digit account_id.

SOLIMI card

payment_type = solimi_card

Requires an 8-digit card_id.

Lifecycle

Status	Meaning
`INITIATED`	The payment request has been created.
`PENDING_APPROVAL`	The payment is waiting for customer approval.
`APPROVED`	The customer approved the payment.
`PROCESSING`	Processing is in progress.
`SUCCESS`	The payment succeeded.
`FAILED`	The payment failed.
`DECLINED`	The payment was declined by the customer or system.
`EXPIRED`	The request expired.
`CANCELLED`	The request was cancelled.

Payload reference and validations

This section defines the purpose of each field, its type, whether it is required, its length and expected format. The regex patterns below are recommended client-side validations so integrators can catch issues before calling the API.

SOLIMI validates payloads strictly. If an optional field does not apply to the selected payment type, do not send it. Example: do not send account_id for a mobile_money payment.

Security headers

Field	Purpose	Type	Required	Length	Regex / Format	Example
`x-api-key`	Identifies the partner API key.	string	Yes	Variable	`^sk_(test\|live)_[A-Za-z0-9]+$`	`sk_test_abcd...`
`x-timestamp`	Protects requests against replay.	numeric string	Yes	10 digits in seconds	`^\d{10}$`, Unix timestamp, 300s tolerance	`1781899200`
`x-signature`	Proves the request was signed by the partner server.	string	Yes	64 characters	`^[a-f0-9]{64}$`	`7d9f...a31c`
`Idempotency-Key`	Prevents duplicate payment creation during retries.	string	Yes for payment creation	Recommended: 1 to 100	`^[A-Za-z0-9._:-]{1,100}$`	`ORDER-2026-0001`

`PaymentRequestCreate` - Payment creation

Field	Business purpose	Type	Required	Length	Regex / Values	Notes
`merchant_reference`	Unique transaction reference in the merchant system.	string	Yes	1 to 100 characters	`^[A-Za-z0-9._:-]{1,100}$` recommended	Use the same value as the basis for the `Idempotency-Key`.
`payment_type`	Payment channel to use.	enum string	Yes	Variable	`mobile_money`, `solimi_account`, `solimi_card`	Determines conditionally required fields.
`amount`	Amount to collect.	integer	Yes	Positive integer	`^[1-9]\d*$`	Amount in XOF, without decimals.
`currency`	Transaction currency.	literal string	No	3 characters	`^XOF$`	Optional. If omitted, the backend applies `XOF`.
`description`	Label used for reconciliation or support.	string	Yes	Minimum 1 character	`^.{1,}$`	Recommended: include the order number.
`customer_phone`	Paying customer phone number.	string	Yes	8 to 20 characters	`^\+?[0-9]{8,20}$` recommended	Send international format when possible.
`provider`	Mobile money operator.	enum string	Yes if `mobile_money`	Variable	`mixx`, `coris_money`, `moov_money`	Do not send for `solimi_account` or `solimi_card`.
`account_id`	Customer SOLIMI account identifier.	string	Yes if `solimi_account`	Exactly 12 digits	`^\d{12}$`	Rejected if length differs from 12.
`card_id`	Customer SOLIMI card identifier.	string	Yes if `solimi_card`	Exactly 8 digits	`^\d{8}$`	Rejected if length differs from 8.

Conditional rules by payment type

`payment_type`	Required field	Fields not to send	Minimal example
`mobile_money`	`provider`	`account_id`, `card_id`	`{"payment_type":"mobile_money","provider":"mixx"}`
`solimi_account`	`account_id`	`provider`, `card_id`	`{"payment_type":"solimi_account","account_id":"1234567890"}`
`solimi_card`	`card_id`	`provider`, `account_id`	`{"payment_type":"solimi_card","card_id":"12345678"}`

`PaymentRequestResponse` - Creation response

Field	Purpose	Type	Format / Values
`reference`	SOLIMI payment reference.	string	`PAY-...`, keep it for tracking.
`merchant_reference`	Merchant reference sent in the request.	string	1 to 100 characters.
`payment_type`	Selected payment type.	enum	`mobile_money`, `solimi_account`, `solimi_card`.
`provider`	Mobile money operator.	enum or null	`mixx`, `coris_money`, `moov_money`, or `null`.
`amount`	Requested amount.	integer	Positive integer.
`currency`	Currency.	string	`XOF`.
`description`	Payment label.	string	Non-empty text.
`customer_phone`	Customer phone number.	string	8 to 20 characters.
`status`	Initial or current state.	enum	See payment status table.
`expires_at`	Request expiration date.	datetime	ISO 8601, UTC recommended.
`created_at`	Creation date.	datetime	ISO 8601.

`PaymentStatusResponse` - Payment tracking

Field	Purpose	Type	Format / Values
`reference`	SOLIMI reference to query.	string	`PAY-...`.
`merchant_reference`	Merchant reference.	string	1 to 100 characters.
`partner_id`	Technical partner identifier.	UUID	`^[0-9a-fA-F-]{36}$`.
`payment_type`	Payment channel.	enum	Supported payment types.
`provider`	Mobile money provider.	enum or null	Null outside mobile money.
`amount`	Amount.	integer	Positive integer.
`currency`	Currency.	string	`XOF`.
`status`	Current status.	enum	`INITIATED`, `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `SUCCESS`, `FAILED`, `DECLINED`, `EXPIRED`, `CANCELLED`.
`failure_reason`	Failure reason if available.	string or null	Mainly used for non-success statuses.
`expires_at`	Expiration date.	datetime	ISO 8601.
`approved_at`	Customer approval date.	datetime or null	ISO 8601.
`completed_at`	Final success date.	datetime or null	ISO 8601.
`failed_at`	Failure date.	datetime or null	ISO 8601.
`declined_at`	Decline date.	datetime or null	ISO 8601.

Webhook payloads

Field	Purpose	Type	Required	Format / Regex
`url`	Partner HTTPS endpoint.	URL	Yes on create	`^https://.+` recommended in production.
`secret`	Secret shared with SOLIMI to authenticate received webhooks.	string	No	Minimum 16 characters. Recommended: 32+ random characters.
`is_active`	Enables or disables delivery.	boolean	No, update only	`true` or `false`.

Public endpoints

The endpoints below are available under the /v1 prefix.

GET/v1/health

Public

Checks API availability.

Headers

Header	Required	Value
`content-type`	No	`application/json`

Payload

No body required.

Possible responses

HTTP	Case	Body
`200`	API available	`{"status":"ok","service":"solimi-payment-api"}`
`5xx`	Service unavailable	Server error or infrastructure timeout.

Code examples

cURL

curl -X GET "{{base_url}}/v1/health"

PHP

<?php
echo file_get_contents("{{base_url}}/v1/health");

Node.js

const response = await fetch("{{base_url}}/v1/health");
console.log(await response.json());

Python

import requests

response = requests.get("{{base_url}}/v1/health")
print(response.json())

200 response example

{
  "status": "ok",
  "service": "solimi-payment-api"
}

POST/v1/payments/request

HMAC + Idempotency-Key

Creates a payment request.

Required headers

Header	Purpose	Format / value
`content-type`	Body format.	`application/json`
`x-api-key`	Identifies the partner.	API key provided by SOLIMI.
`x-timestamp`	Replay protection.	Unix timestamp in seconds, 300s tolerance.
`x-signature`	Authenticates the request.	Hex HMAC SHA-256 of `raw_body + timestamp`.
`Idempotency-Key`	Prevents duplicate creation on retries.	Unique per logical attempt, e.g. `ORDER-2026-0001`.

Payload and validations

Field	Type	Required	Values / regex	Purpose
`merchant_reference`	string	Yes	1-100, `^[A-Za-z0-9._:-]{1,100}$`	Unique merchant-side reference.
`payment_type`	enum	Yes	`mobile_money`, `solimi_account`, `solimi_card`	Collection channel.
`provider`	enum/null	Yes for mobile money	`mixx`, `moov_money`, `coris_money`	Mobile money operator.
`amount`	integer	Yes	`^[1-9]\d*$`	XOF amount without decimals.
`currency`	string	No	`XOF`	Optional. Default currency applied by the backend.
`description`	string	Yes	Non-empty	Reconciliation label.
`customer_phone`	string	Yes	`^\+?[0-9]{8,20}$`	Paying customer phone.
`account_id`	string/null	Yes for SOLIMI account	`^\d{12}$`	Customer SOLIMI account.
`card_id`	string/null	Yes for SOLIMI card	`^\d{8}$`	Customer SOLIMI card.

Payload example

{
  "merchant_reference": "ORDER-2026-0001",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "description": "Order ORDER-2026-0001",
  "customer_phone": "22890112233"
}

Possible responses

HTTP	Application code	Case
`201`	-	Payment request created.
`400`	`domain_error`	Invalid business rule.
`401`	`authentication_failed`	Missing or invalid HMAC headers.
`403`	`authorization_failed`	IP not allowed, inactive partner or invalid credentials.
`409`	`idempotency_conflict` / `duplicate_merchant_reference`	Idempotency key reused with another payload or merchant reference already used.
`422`	`validation_error`	Missing field or invalid format.
`500`	`payment_core_sync_failed`	Internal synchronization error with the SOLIMI core.

Code examples

cURL

BODY='{"merchant_reference":"ORDER-2026-0001","payment_type":"mobile_money","provider":"mixx","amount":25000,"description":"Order ORDER-2026-0001","customer_phone":"22890112233"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s%s" "$BODY" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')

curl -X POST "{{base_url}}/v1/payments/request" \
  -H "content-type: application/json" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -H "Idempotency-Key: ORDER-2026-0001" \
  -d "$BODY"

PHP

<?php
$apiKey = getenv("SOLIMI_API_KEY");
$apiSecret = getenv("SOLIMI_API_SECRET");
$timestamp = (string) time();
$body = json_encode([
  "merchant_reference" => "ORDER-2026-0001",
  "payment_type" => "mobile_money",
  "provider" => "mixx",
  "amount" => 25000,
  "description" => "Order ORDER-2026-0001",
  "customer_phone" => "22890112233"
], JSON_UNESCAPED_SLASHES);
$signature = hash_hmac("sha256", $body . $timestamp, $apiSecret);

$ch = curl_init("{{base_url}}/v1/payments/request");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_HTTPHEADER => [
    "content-type: application/json",
    "x-api-key: $apiKey",
    "x-timestamp: $timestamp",
    "x-signature: $signature",
    "Idempotency-Key: ORDER-2026-0001"
  ]
]);
echo curl_exec($ch);

Node.js

import crypto from "node:crypto";

const body = JSON.stringify({
  merchant_reference: "ORDER-2026-0001",
  payment_type: "mobile_money",
  provider: "mixx",
  amount: 25000,
  description: "Order ORDER-2026-0001",
  customer_phone: "22890112233"
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(body + timestamp).digest("hex");

const response = await fetch("{{base_url}}/v1/payments/request", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.SOLIMI_API_KEY,
    "x-timestamp": timestamp,
    "x-signature": signature,
    "Idempotency-Key": "ORDER-2026-0001"
  },
  body
});
console.log(await response.json());

Python

import hashlib
import hmac
import json
import os
import time
import requests

payload = {
    "merchant_reference": "ORDER-2026-0001",
    "payment_type": "mobile_money",
    "provider": "mixx",
    "amount": 25000,
    "description": "Order ORDER-2026-0001",
    "customer_phone": "22890112233",
}
body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), (body + timestamp).encode(), hashlib.sha256).hexdigest()

response = requests.post(
    "{{base_url}}/v1/payments/request",
    data=body.encode(),
    headers={
        "content-type": "application/json",
        "x-api-key": os.environ["SOLIMI_API_KEY"],
        "x-timestamp": timestamp,
        "x-signature": signature,
        "Idempotency-Key": "ORDER-2026-0001",
    },
)
print(response.json())

201 response example

{
  "reference": "PAY-8C7F36A1B2",
  "merchant_reference": "ORDER-2026-0001",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "description": "Order ORDER-2026-0001",
  "customer_phone": "22890112233",
  "status": "PENDING_APPROVAL",
  "expires_at": "2026-06-19T21:00:00Z",
  "created_at": "2026-06-19T20:45:00Z"
}

GET/v1/payments/status/{reference}

HMAC

Returns the current payment status.

Required headers

Header	Purpose	Format / value
`x-api-key`	Identifies the partner.	API key provided by SOLIMI.
`x-timestamp`	Replay protection.	Unix timestamp in seconds.
`x-signature`	Authenticates the GET request.	Hex HMAC SHA-256 of `timestamp`.

Parameters

Parameter	Type	Required	Format	Purpose
`reference`	path string	Yes	`PAY-...` or `SOLPAY...`	SOLIMI reference returned on creation.

Possible responses

HTTP	Application code	Case
`200`	-	Status returned.
`401`	`authentication_failed`	Invalid signature.
`403`	`authorization_failed`	Unauthorized partner.
`404`	`not_found`	Unknown reference for this partner.

Code examples

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/payments/status/PAY-8C7F36A1B2" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/payments/status/PAY-8C7F36A1B2", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/payments/status/PAY-8C7F36A1B2", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/payments/status/PAY-8C7F36A1B2",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

200 response example

{
  "reference": "PAY-8C7F36A1B2",
  "merchant_reference": "ORDER-2026-0001",
  "partner_id": "945adbc3-1e63-46da-8128-8ef790b50714",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "status": "SUCCESS",
  "failure_reason": null,
  "expires_at": "2026-06-19T21:00:00Z",
  "approved_at": "2026-06-19T20:46:11Z",
  "completed_at": "2026-06-19T20:46:18Z",
  "failed_at": null,
  "declined_at": null
}

GET/v1/account/balance

HMAC

Returns the partner available and reserved balances.

Required headers

Header	Purpose	Format / value
`x-api-key`	Identifies the partner.	API key provided by SOLIMI.
`x-timestamp`	Replay protection.	Unix timestamp in seconds.
`x-signature`	Authenticates the GET request.	Hex HMAC SHA-256 of `timestamp`.

Payload

No body required.

Possible responses

HTTP	Application code	Case
`200`	-	Balance returned.
`401`	`authentication_failed`	Invalid signature.
`403`	`authorization_failed`	Unauthorized partner.

Code examples

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/account/balance" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/account/balance", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/account/balance", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/account/balance",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

200 response example

{
  "partner_reference": "PART-637C64AC5B75",
  "currency": "XOF",
  "available_balance": 1250000,
  "reserved_balance": 50000,
  "environment": "sandbox"
}

GET/v1/payment-methods

HMAC

Lists active payment methods.

Required headers

Header	Purpose	Format / value
`x-api-key`	Identifies the partner.	API key provided by SOLIMI.
`x-timestamp`	Replay protection.	Unix timestamp in seconds.
`x-signature`	Authenticates the GET request.	Hex HMAC SHA-256 of `timestamp`.

Payload

No body required.

Response fields

Field	Type	Possible values	Purpose
`code`	string	`mixx`, `moov_money`, `solimi_account`	Technical code to send as `provider` when applicable.
`name`	string	Human label	Display name.
`provider`	string/null	Mobile money provider or null	Linked operator.
`is_active`	boolean	`true`/`false`	Method availability.

Possible responses

HTTP	Application code	Case
`200`	-	List returned.
`401`	`authentication_failed`	Invalid signature.
`403`	`authorization_failed`	Unauthorized partner.

Code examples

cURL

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf "%s" "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SOLIMI_API_SECRET" -hex | sed 's/^.* //')
curl -X GET "{{base_url}}/v1/payment-methods" \
  -H "x-api-key: $SOLIMI_API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE"

PHP

<?php
$timestamp = (string) time();
$signature = hash_hmac("sha256", $timestamp, getenv("SOLIMI_API_SECRET"));
$opts = ["http" => ["header" => "x-api-key: ".getenv("SOLIMI_API_KEY")."\r\nx-timestamp: $timestamp\r\nx-signature: $signature\r\n"]];
echo file_get_contents("{{base_url}}/v1/payment-methods", false, stream_context_create($opts));

Node.js

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac("sha256", process.env.SOLIMI_API_SECRET).update(timestamp).digest("hex");
const response = await fetch("{{base_url}}/v1/payment-methods", {
  headers: {"x-api-key": process.env.SOLIMI_API_KEY, "x-timestamp": timestamp, "x-signature": signature}
});
console.log(await response.json());

Python

import hashlib, hmac, os, time, requests

timestamp = str(int(time.time()))
signature = hmac.new(os.environ["SOLIMI_API_SECRET"].encode(), timestamp.encode(), hashlib.sha256).hexdigest()
response = requests.get(
    "{{base_url}}/v1/payment-methods",
    headers={"x-api-key": os.environ["SOLIMI_API_KEY"], "x-timestamp": timestamp, "x-signature": signature},
)
print(response.json())

200 response example

[
  {
    "code": "mixx",
    "name": "Mixx by Yas",
    "provider": "mixx",
    "is_active": true
  },
  {
    "code": "moov_money",
    "name": "Moov Money",
    "provider": "moov_money",
    "is_active": true
  }
]

The partner webhook URL is configured by SOLIMI in the internal developer platform. There is no public endpoint allowing partners to create or update their webhook by themselves.

Postman collection

The SOLIMI Postman collection bundles ready-to-run requests for the public endpoints: payment creation, payment status lookup, partner balance and available payment methods. It helps technical teams start testing quickly without rebuilding headers and payloads from scratch.

How to use it

Download the collection JSON file.
In Postman, click Import, then select the downloaded file.
Fill the base_url, api_key, api_secret and test values.
Run requests from 03 - Payments to validate the integration.

Available file

JSON format compatible with Postman. The collection includes scripts to compute HMAC headers and automatically add the idempotency key on payment requests.

Download Postman collection

The collection does not contain your secrets. Sensitive values must be stored in your Postman environment variables and must not be shared publicly.

Webhooks

SOLIMI calls your webhook endpoint whenever a payment changes state. Your server must respond with an HTTP 2xx status. On failure, SOLIMI retries after 30s, 60s, 300s and 900s.

SOLIMI header	Description
`x-solimi-signature`	Webhook secret shared with SOLIMI. Compare this value with the configured secret.
`x-solimi-timestamp`	Unix timestamp in seconds, useful to reject old notifications.
`x-solimi-event`	Event name, for example `payment.success`.

Events

payment.initiated, payment.pending_approval, payment.success, payment.failed, payment.declined, payment.expired.

FastAPI webhook verification

import time

from fastapi import APIRouter, Header, HTTPException, Request

router = APIRouter()

SOLIMI_WEBHOOK_SECRET = "secret_provided_by_solimi"
SIGNATURE_TOLERANCE_SECONDS = 300


@router.post("/webhooks/solimi/payments")
async def solimi_payment_webhook(
    request: Request,
    x_solimi_signature: str = Header(...),
    x_solimi_timestamp: str = Header(...),
    x_solimi_event: str = Header(...),
):
    if x_solimi_signature != SOLIMI_WEBHOOK_SECRET:
        raise HTTPException(status_code=401, detail="Invalid webhook signature")

    try:
        timestamp = int(x_solimi_timestamp)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid timestamp")

    if abs(int(time.time()) - timestamp) > SIGNATURE_TOLERANCE_SECONDS:
        raise HTTPException(status_code=400, detail="Expired webhook timestamp")

    payload = await request.json()
    payment = payload.get("payment", {})

    # Update the partner order/invoice here.
    # Example: payment.success => order paid.

    return {
        "received": True,
        "event": x_solimi_event,
        "merchant_reference": payment.get("merchant_reference"),
        "solimi_reference": payment.get("reference"),
        "status": payment.get("status"),
    }

Verification is intentionally simple: x-solimi-signature directly contains the webhook secret. Keep this secret server-side only.

Errors

Errors are returned as JSON.

{
  "code": "authentication_failed",
  "message": "Missing authentication headers",
  "details": null
}

HTTP	Code	Recommended action
401	`authentication_failed`	Check HMAC headers, timestamp and signature.
403	`authorization_failed`	Check allowed IP, API key status and partner status.
404	`not_found`	Check the payment reference or requested route.
409	`idempotency_conflict`	Reuse the same key only for the same logical request.
422	`validation_error`	Fix invalid fields in the payload.

Production checklist

Store the API key and API secret in a server-side secrets manager.
Sign every request with the exact body sent to SOLIMI.
Use a unique idempotency key for every merchant payment.
Verify webhooks by comparing x-solimi-signature with the configured webhook secret.
Implement status polling as a fallback when a webhook is temporarily unavailable.
Provide SOLIMI with the public IP addresses of your servers.
Test success, failure, decline, expiration and webhook retry cases in sandbox.

Documentation d'integration SOLIMI pour marchands, fintechs et banques

Environnements et pre-requis

Authentification HMAC

Headers obligatoires

Algorithme

Paiements

Mobile money

Compte SOLIMI

Carte SOLIMI

Cycle de vie

Reference des payloads et validations

Headers de securite

PaymentRequestCreate - Creation d'un paiement

Regles conditionnelles par type de paiement

PaymentRequestResponse - Reponse de creation

PaymentStatusResponse - Suivi de paiement

Payloads webhook

Endpoints publics

GET/v1/health

Headers

Payload

Reponses possibles

Exemples d'appel

Exemple de reponse 200

POST/v1/payments/request

Headers obligatoires

Payload et validations

Exemple de payload

Reponses possibles

Exemples d'appel

Exemple de reponse 201

GET/v1/payments/status/{reference}

Headers obligatoires

Parametres

Reponses possibles

Exemples d'appel

Exemple de reponse 200

GET/v1/account/balance

Headers obligatoires

Payload

Reponses possibles

Exemples d'appel

Exemple de reponse 200

GET/v1/payment-methods

Headers obligatoires

Payload

Champs de reponse

Reponses possibles

Exemples d'appel

Exemple de reponse 200

Collection Postman

Comment l'utiliser

Fichier disponible

Webhooks

Evenements

Verification webhook FastAPI

Erreurs

Checklist de mise en production

SOLIMI integration documentation for merchants, fintechs and banks

Environments and requirements

HMAC authentication

Required headers

Algorithm

Payments

Mobile money

SOLIMI account

SOLIMI card

Lifecycle

Payload reference and validations

Security headers

PaymentRequestCreate - Payment creation

Conditional rules by payment type

PaymentRequestResponse - Creation response

PaymentStatusResponse - Payment tracking

Webhook payloads

Public endpoints

GET/v1/health

Headers

Payload

Possible responses

`PaymentRequestCreate` - Creation d'un paiement

`PaymentRequestResponse` - Reponse de creation

`PaymentStatusResponse` - Suivi de paiement

`PaymentRequestCreate` - Payment creation

`PaymentRequestResponse` - Creation response

`PaymentStatusResponse` - Payment tracking