API publique de collecte de paiement

Documentation d'intégration SOLIMI pour marchands, fintechs et banques

Ce guide explique comment connecter votre application à l'API publique SOLIMI pour initier des paiements directs, créer des sessions checkout hébergées, consulter leur statut, récupérer les moyens disponibles et recevoir les notifications webhook.

REST JSON HMAC-SHA256 Idempotence Webhooks sécurisés

Télécharger la collection Postman

Authentification Chaque requête est signée avec votre clé secrète API.

Devise Les transactions de collecte sont exprimées en XOF.

Canaux Mobile money, carte bancaire et carte virtuelle SOLIMI.

Environnements et prérequis

Avant l'intégration, l'équipe SOLIMI vous fournit un compte partenaire, une clé API, un secret API et configure les adresses IP autorisées. Le secret API est affiché une seule fois: conservez-le dans un coffre de secrets.

Environnement	Base URL	Usage
Sandbox	`https://sandbox-api.solimi.co`	Intégration partenaire avant mise en production.
Production	`https://api.solimi.co`	Transactions réelles après validation SOLIMI.

Les domaines sandbox et production ci-dessus sont les URLs de référence à confirmer avec SOLIMI lors de l'onboarding. Ne partagez jamais votre secret API dans un frontend, une application mobile ou un dépôt Git.

Simulation sandbox. Pendant la phase d'intégration, les paiements initiés en sandbox ne déclenchent pas toujours un débit réel chez les opérateurs Mobile Money ou sur les cartes virtuelles SOLIMI. SOLIMI met donc à disposition un simulateur de retour provider pour reproduire les cas SUCCESS, DECLINED, FAILED et TIMEOUT. Le simulateur s'utilise après la création d'un paiement, avec la référence SOLIMI retournée par l'API. Il met à jour le statut du paiement et déclenche le webhook partenaire comme le ferait un callback provider réel. Cette fonctionnalité est réservée à la sandbox et n'est pas disponible en production.

Authentification HMAC

Toutes les routes publiques sécurisées utilisent une signature HMAC SHA-256. SOLIMI vérifie votre clé API, l'adresse IP source, l'horodatage et la signature calculée à partir du corps exact de la requête.

Headers obligatoires

Header	Description
`x-api-key`	Votre clé API publique, par exemple `sk_test_...` ou `sk_live_...`.
`x-timestamp`	Timestamp Unix en secondes. La tolérance est de 300 secondes.
`x-signature`	HMAC SHA-256 hexadécimal du message `raw_body + timestamp`.
`Idempotency-Key`	Obligatoire pour `POST /v1/payments/request`. Doit être unique par tentative logique.

Algorithme

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

Pour une requête GET, le corps est vide. Le message signé est donc uniquement le timestamp.

Protection contre les tentatives abusives

Si une clé API valide est utilisée avec de mauvaises signatures ou de mauvais timestamps à répétition, SOLIMI bloque temporairement l'authentification de cette clé afin de limiter les tentatives de force brute sur le secret API.

Le blocage est temporaire et retourne 429 api_key_temporarily_locked.
La durée standard du blocage est de 15 minutes.
Les appels depuis une IP non autorisée restent refusés en 403 authorization_failed.

Choisir son mode d'intégration

SOLIMI propose deux façons d'encaisser un paiement. Le choix dépend du niveau de contrôle que vous voulez garder sur l'expérience utilisateur.

1. API directe

Votre plateforme affiche ses propres formulaires de paiement, collecte le numéro de téléphone ou la carte virtuelle SOLIMI, puis appelle directement l'API SOLIMI.

Endpoint principal: POST /v1/payments/request.
Suivi: GET /v1/payments/status/{reference}.
Idéal si vous maîtrisez déjà votre propre interface de paiement.

2. Page de paiement hébergée

Votre backend crée une session checkout. SOLIMI retourne un lien de paiement; le client est redirigé vers une page SOLIMI où il choisit Mixx, Moov Money, carte bancaire ou carte virtuelle SOLIMI.

Création: POST /v1/checkout/sessions.
Suivi: GET /v1/checkout/sessions/{reference}.
Idéal pour intégrer vite sans développer l'interface de choix du moyen de paiement.

1. API directe

Ce mode est l'intégration où votre propre application pilote l'interface de paiement. Votre backend appelle directement POST /v1/payments/request, puis suit le statut avec GET /v1/payments/status/{reference} et les webhooks.

Une demande de paiement crée une intention de collecte. Selon le type de paiement, le client approuve le paiement sur mobile money, via une carte virtuelle SOLIMI ou sur une page bancaire sécurisée.

Mobile money

payment_type = mobile_money

Requiert provider: mixx, coris_money ou moov_money.

Carte virtuelle SOLIMI

payment_type = solimi_card

Requiert card_id sur 8 chiffres.

Carte bancaire

payment_type = bank_card

Retourne un provider_payment_url pour rediriger le client vers Visa/Mastercard.

Cycle de vie

Statut	Signification
`INITIATED`	La demande de paiement est créée.
`PENDING_APPROVAL`	Le paiement attend l'approbation du client.
`APPROVED`	Le client a approuvé le paiement.
`PROCESSING`	Le traitement est en cours.
`SUCCESS`	Le paiement est réussi.
`FAILED`	Le paiement a échoué.
`DECLINED`	Le client ou le système a refusé le paiement.
`EXPIRED`	La demande a expiré.
`CANCELLED`	La demande a été annulée.

2. Page de paiement hébergée SOLIMI

Ce mode est l'intégration où SOLIMI héberge l'interface de choix du moyen de paiement. Le partenaire ne développe pas l'écran de paiement: il crée une session, reçoit un lien, puis redirige le client.

Le checkout hébergé permet au partenaire d'appeler une seule API pour créer une session de paiement. SOLIMI retourne ensuite un payment_url à ouvrir côté client. Sur cette page, le client final choisit son moyen de paiement: Mixx, Moov Money, carte virtuelle SOLIMI ou carte bancaire.

Quand utiliser le mode 2

Vous souhaitez déléguer l'interface de choix du moyen de paiement à SOLIMI.
Vous ne voulez pas intégrer séparément chaque provider dans votre application.
Vous voulez un parcours web simple avec redirection vers votre site après paiement.

Redirections

Les URLs de succès, d'échec et d'annulation peuvent être configurées sur la fiche partenaire par SOLIMI. Le payload peut aussi les surcharger ponctuellement, mais ce n'est pas nécessaire dans le flux standard.

Endpoints à intégrer côté partenaire

POST `/v1/checkout/sessions`

Crée la session de paiement et retourne le lien à ouvrir côté client.

Payload standard

{
  "merchant_reference": "CMD-20260729-001",
  "amount": 12500,
  "description": "Vente de chaussure",
  "customer_phone": "22891390850",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

Réponse 201

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_url": "https://pay.solimi.co/checkout/CHK-20260729-8F2A91",
  "amount": 12500,
  "currency": "XOF",
  "description": "Vente de chaussure",
  "status": "created",
  "expires_at": "2026-07-29T12:30:00Z"
}

Erreurs possibles: 401 authentication_failed, 403 authorization_failed, 409 duplicate_merchant_reference, 422 validation_error.

GET `/v1/checkout/sessions/{reference}`

Consulte l'état d'une session checkout en secours du webhook.

Payload

Aucun body requis. La requête reste signée en HMAC avec un body vide.

Réponse 200

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Vente de chaussure",
  "status": "payment_initiated",
  "selected_payment_type": "mobile_money",
  "selected_provider": "mixx",
  "provider_payment_url": null,
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

Erreurs possibles: 401 authentication_failed, 403 authorization_failed, 404 not_found.

Flux recommandé

Votre backend crée une session avec POST /v1/checkout/sessions.
Vous redirigez le client vers le payment_url retourné.
Le client choisit un moyen de paiement sur la page SOLIMI Checkout.
SOLIMI exécute le paiement, met à jour le statut et appelle votre webhook.
Votre backend peut consulter GET /v1/checkout/sessions/{reference} en secours.

Le checkout hébergé cohabite avec POST /v1/payments/request. Gardez le paiement direct si vous maîtrisez déjà votre propre interface de paiement; utilisez le checkout si vous voulez un parcours SOLIMI prêt à l'emploi.

Référence des payloads et validations

Cette section précise le rôle de chaque champ, son type, son caractère obligatoire, sa taille et le format attendu. Les regex ci-dessous sont les validations recommandées côté intégrateur, afin de détecter 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 provider pour un paiement solimi_card.

Headers de sécurité

Champ	Rôle	Type	Obligatoire	Taille	Regex / Format	Exemple
`x-api-key`	Identifie la clé API du partenaire.	string	Oui	Variable	`^sk_(test\|live)_[A-Za-z0-9]+$`	`sk_test_abcd...`
`x-timestamp`	Protège contre le rejeu de requêtes.	string numeric	Oui	10 chiffres en secondes	`^\d{10}$`, Unix timestamp, tolérance 300s	`1781899200`
`x-signature`	Prouve que la requête vient du serveur partenaire.	string	Oui	64 caractères	`^[a-f0-9]{64}$`	`7d9f...a31c`
`Idempotency-Key`	Évite la création de doublons lors des retries.	string	Oui pour création paiement	Recommandé: 1 à 100	`^[A-Za-z0-9._:-]{1,100}$`	`ORDER-2026-0001`

`PaymentRequestCreate` - Création d'un paiement

Champ	Rôle métier	Type	Obligatoire	Taille	Regex / Valeurs	Notes
`merchant_reference`	Référence unique de la transaction dans le système du marchand.	string	Oui	1 à 100 caractères	`^[A-Za-z0-9._:-]{1,100}$` recommandé	Utilisez la même valeur comme base de `Idempotency-Key`.
`payment_type`	Canal de paiement à utiliser.	enum string	Oui	Variable	`mobile_money`, `bank_card`, `solimi_card`	Détermine les champs conditionnels requis.
`amount`	Montant à collecter.	integer	Oui	Nombre entier positif	`^[1-9]\d*$`	Montant en XOF, sans décimales.
`currency`	Devise de la transaction.	literal string	Non	3 caractères	`^XOF$`	Facultatif. Si absent, le backend applique `XOF`.
`description`	Libellé visible pour réconciliation ou support.	string	Oui	Minimum 1 caractère	`^.{1,}$`	Recommandé: inclure le numéro de commande.
`customer_phone`	Numéro du client payeur.	string	Oui	8 à 20 caractères	`^\+?[0-9]{8,20}$` recommandé	Envoyez le numéro au format international quand possible.
`customer_first_name`	Prénom du client final.	string	Non	Maximum 100 caractères	`^.{0,100}$`	Utilisé pour l'historique, la réconciliation et le support. Non affiché sur le checkout.
`customer_last_name`	Nom du client final.	string	Non	Maximum 100 caractères	`^.{0,100}$`	Utilisé pour l'historique, la réconciliation et le support. Non affiché sur le checkout.
`provider`	Opérateur mobile money à utiliser.	enum string	Oui si `mobile_money`	Variable	`mixx`, `coris_money`, `moov_money`, `bank_card`	Obligatoire pour `mobile_money`. Pour `bank_card`, le backend applique automatiquement `bank_card`.
`coris_country_code`	Code pays Coris Money fixé par SOLIMI.	string	Non	1 à 10 caractères	Toujours `228`	Le backend utilise automatiquement `228` pour construire l'appel Coris Money.
`coris_otp`	Code OTP saisi par le client Coris Money.	string	Oui si `provider=coris_money`	1 à 20 caractères	Exemple: `123456`	Transmis au provider Coris Money pour valider le débit.
`card_id`	Carte ID de la carte virtuelle SOLIMI client.	string	Oui si `solimi_card`	Exactement 8 chiffres	`^\d{8}$`	Visible dans l'application SOLIMI sur la carte virtuelle. Différent du numéro complet de carte à 16 chiffres.

Important pour la carte virtuelle SOLIMI. Le champ card_id correspond au Carte ID affiché sur la carte virtuelle dans l'application SOLIMI, par exemple 24924478. Il ne faut pas envoyer le numéro complet de la carte bancaire virtuelle à 16 chiffres.

Parcours Coris Money en 2 étapes. Avant d'appeler POST /v1/payments/request avec provider=coris_money, appelez d'abord POST /v1/payments/coris-money/otp avec phone. SOLIMI vérifie l'existence du compte Coris Money et déclenche l'envoi de l'OTP. Le client saisit ensuite cet OTP dans coris_otp lors de la création du paiement.

Règles conditionnelles par type de paiement

`payment_type`	Champ requis	Champs à ne pas envoyer	Exemple minimal
`mobile_money`	`provider`	`card_id`	`{"payment_type":"mobile_money","provider":"mixx"}`
`mobile_money` + `coris_money`	`provider`, `coris_otp`	`card_id`	`{"payment_type":"mobile_money","provider":"coris_money","coris_otp":"123456"}`
`bank_card`	Aucun champ conditionnel	`card_id`	`{"payment_type":"bank_card"}`
`solimi_card`	`card_id`	`provider`	`{"payment_type":"solimi_card","card_id":"12345678"}`

`PaymentRequestResponse` - Réponse de création

Champ	Rôle	Type	Format / Valeurs
`reference`	Référence SOLIMI du paiement.	string	`PAY-...`, à conserver pour le suivi.
`merchant_reference`	Référence marchand transmise dans la requête.	string	1 à 100 caractères.
`payment_type`	Type de paiement retenu.	enum	`mobile_money`, `bank_card`, `solimi_card`.
`provider`	Opérateur ou provider technique.	enum ou null	`mixx`, `coris_money`, `moov_money`, `bank_card`, ou `null`.
`amount`	Montant demandé.	integer	Entier positif.
`currency`	Devise.	string	`XOF`.
`description`	Libellé de la demande.	string	Texte non vide.
`customer_phone`	Numéro client.	string	8 à 20 caractères.
`provider_payment_url`	Lien de paiement externe à ouvrir pour la carte bancaire.	URL ou null	Renseigné principalement quand `payment_type=bank_card`.
`status`	État initial ou courant.	enum	Voir la table des statuts.
`expires_at`	Date d'expiration de la demande.	datetime	ISO 8601, UTC recommandé.
`created_at`	Date de création.	datetime	ISO 8601.

`PaymentStatusResponse` - Suivi de paiement

Champ	Rôle	Type	Format / Valeurs
`reference`	Référence SOLIMI à interroger.	string	`PAY-...`.
`merchant_reference`	Référence du marchand.	string	1 à 100 caractères.
`payment_type`	Canal utilisé.	enum	Types de paiement supportés.
`provider`	Provider mobile money.	enum ou null	Null hors mobile money.
`amount`	Montant.	integer	Entier positif.
`currency`	Devise.	string	`XOF`.
`status`	État courant.	enum	`INITIATED`, `PENDING_APPROVAL`, `APPROVED`, `PROCESSING`, `SUCCESS`, `FAILED`, `DECLINED`, `EXPIRED`, `CANCELLED`.
`provider_payment_url`	Lien de paiement bancaire si disponible.	URL ou null	À utiliser pour rediriger le client vers la page sécurisée Visa/Mastercard.
`failure_reason`	Cause d'échec si disponible.	string ou null	Renseigne principalement les statuts non réussis.
`expires_at`	Expiration.	datetime	ISO 8601.
`approved_at`	Date d'approbation client.	datetime ou null	ISO 8601.
`completed_at`	Date de succès final.	datetime ou null	ISO 8601.
`failed_at`	Date d'échec.	datetime ou null	ISO 8601.
`declined_at`	Date de refus.	datetime ou null	ISO 8601.

Payloads webhook

Champ	Rôle	Type	Obligatoire	Format / Regex
`url`	Endpoint HTTPS du partenaire.	URL	Oui à la création	`^https://.+` recommandé en production.
`secret`	Secret partagé avec SOLIMI pour authentifier les webhooks reçus.	string	Non	Minimum 16 caractères. Recommandé: 32+ caractères aléatoires.
`is_active`	Active ou désactive la réception.	boolean	Non, uniquement update	`true` ou `false`.

Endpoints publics par mode d'intégration

Les endpoints ci-dessous sont regroupés selon leur usage: mode 1 API directe pour piloter votre propre interface de paiement, et mode 2 page hébergée pour rediriger le client vers SOLIMI Checkout. Les endpoints partenaire sont accessibles sous le préfixe /v1.

GET/v1/health

Public

Vérifie la disponibilité de l'API.

Headers

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

Payload

Aucun body requis.

Réponses 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 réponse 200

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

POST/v1/payments/request

HMAC + Idempotency-Key

Mode 1 - API directe. Crée une demande de paiement depuis votre propre interface.

Headers obligatoires

Header	Rôle	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, tolérance 300s.
`x-signature`	Authentifie la requête.	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	Rôle
`merchant_reference`	string	Oui	1-100, `^[A-Za-z0-9._:-]{1,100}$`	Référence unique côté marchand.
`payment_type`	enum	Oui	`mobile_money`, `bank_card`, `solimi_card`	Canal de collecte.
`provider`	enum/null	Oui si mobile money	`mixx`, `moov_money`, `coris_money`, `bank_card`	Opérateur mobile money. Pour `bank_card`, le backend le renseigne automatiquement.
`coris_country_code`	string/null	Non	Toujours `228`	Code pays Coris fixé automatiquement par le backend.
`coris_otp`	string/null	Oui si Coris Money	Max 20 caractères	OTP Coris Money saisi par le client.
`amount`	integer	Oui	`^[1-9]\d*$`	Montant XOF sans décimales.
`currency`	string	Non	`XOF`	Facultatif. Devise par defaut appliquee par le backend.
`description`	string	Oui	Non vide	Libelle/réconciliation.
`customer_phone`	string	Oui	`^\+?[0-9]{8,20}$`	Numéro du client payeur.
`customer_first_name`	string/null	Non	Max 100 caractères	Prénom conservé pour l'historique et le support.
`customer_last_name`	string/null	Non	Max 100 caractères	Nom conservé pour l'historique et le support.
`card_id`	string/null	Oui si carte virtuelle SOLIMI	`^\d{8}$`	Carte ID de 8 chiffres visible sur la carte virtuelle dans l'application SOLIMI. Ne pas envoyer le numéro complet à 16 chiffres.

Carte virtuelle SOLIMI. Pour payment_type = solimi_card, le partenaire doit envoyer le card_id de 8 chiffres affiché dans l'application SOLIMI, et non le numéro complet de la carte.

Exemple de payload

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

Exemple carte bancaire

{
  "merchant_reference": "ORDER-2026-0002",
  "payment_type": "bank_card",
  "amount": 25000,
  "description": "Commande ORDER-2026-0002",
  "customer_phone": "22890112233",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

Réponses possibles

HTTP	Code applicatif	Cas
`201`	-	Demande de paiement créée.
`400`	`domain_error`	Règle métier invalide.
`401`	`authentication_failed`	Headers HMAC manquants ou invalides.
`403`	`authorization_failed`	IP non autorisée, partenaire inactif ou credentials invalides.
`409`	`idempotency_conflict` / `duplicate_merchant_reference`	Clé idempotente réutilisée avec un payload différent ou référence marchand déjà utilisée.
`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 réponse 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",
  "provider_payment_url": null,
  "expires_at": "2026-06-19T21:00:00Z",
  "created_at": "2026-06-19T20:45:00Z"
}

GET/v1/payments/status/{reference}

HMAC

Mode 1 - API directe. Retourne l'état courant d'un paiement initié via l'API directe.

Headers obligatoires

Header	Rôle	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 requête GET.	HMAC SHA-256 hex du `timestamp`.

Parametres

Parametre	Type	Obligatoire	Format	Rôle
`reference`	path string	Oui	`PAY-...` ou `SOLPAY...`	Référence SOLIMI retournée à la création.

Réponses possibles

HTTP	Code applicatif	Cas
`200`	-	Statut retourne.
`401`	`authentication_failed`	Signature invalide.
`403`	`authorization_failed`	Partenaire non autorise.
`404`	`not_found`	Référence 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 réponse 200

{
  "reference": "PAY-8C7F36A1B2",
  "merchant_reference": "ORDER-2026-0001",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "status": "SUCCESS",
  "provider_payment_url": null,
  "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/payment-methods

HMAC

Liste les moyens de paiement actifs.

Headers obligatoires

Header	Rôle	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 requête GET.	HMAC SHA-256 hex du `timestamp`.

Payload

Aucun body requis.

Champs de réponse

Champ	Type	Valeurs possibles	Rôle
`code`	string	`mixx`, `coris_money`, `moov_money`, `bank_card`, `solimi_card`	Code technique à envoyer dans `provider` si applicable.
`name`	string	Libellé humain	Nom affichable.
`provider`	string/null	Provider mobile money ou null	Operateur associe.
`is_active`	boolean	`true`/`false`	Disponibilite du moyen.

Réponses possibles

HTTP	Code applicatif	Cas
`200`	-	Liste retournée.
`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 réponse 200

[
  {
    "code": "mixx",
    "name": "Mixx by Yas",
    "provider": "mixx",
    "is_active": true
  },
  {
    "code": "mobile_money",
    "name": "Coris Money",
    "provider": "coris_money",
    "is_active": true
  },
  {
    "code": "moov_money",
    "name": "Moov Money",
    "provider": "moov_money",
    "is_active": true
  },
  {
    "code": "bank_card",
    "name": "Carte bancaire",
    "provider": "bank_card",
    "is_active": true
  },
  {
    "code": "solimi_card",
    "name": "Carte virtuelle SOLIMI",
    "provider": null,
    "is_active": true
  }
]

POST/v1/checkout/sessions

HMAC + Idempotency-Key

Mode 2 - Page de paiement hébergée. Crée une session checkout et retourne le lien de paiement à afficher au client.

Headers obligatoires

Header	Rôle	Format / valeur
`content-type`	Format du body.	`application/json`
`x-api-key`	Identifie le partenaire.	Clé API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes, tolérance 300s.
`x-signature`	Authentifie la requête.	HMAC SHA-256 hex de `raw_body + timestamp`.
`Idempotency-Key`	Évite les doublons lors des retries.	Unique par tentative logique.

Payload et validations

Champ	Type	Obligatoire	Valeurs / regex	Rôle
`merchant_reference`	string	Oui	1-100, `^[A-Za-z0-9._:-]{1,100}$`	Référence unique côté marchand.
`amount`	integer	Oui	`^[1-9]\d*$`	Montant à collecter en XOF.
`description`	string	Oui	Non vide	Libellé affiché au client.
`customer_email`	string/null	Non	Email valide, max 255	Facultatif, utilisé uniquement pour l'historique/support. Aucun email automatique n'est envoyé au payeur.
`customer_phone`	string/null	Non	`^\+?[0-9]{8,20}$`	Pré-remplissage du numéro client.
`customer_first_name`	string/null	Non	Max 100 caractères	Prénom conservé pour l'historique. Non affiché sur la page checkout.
`customer_last_name`	string/null	Non	Max 100 caractères	Nom conservé pour l'historique. Non affiché sur la page checkout.
`currency`	string	Non	`XOF`	Facultatif. Par défaut le backend applique `XOF`.
`success_url`, `failure_url`, `cancel_url`	URL/null	Non	URL HTTPS recommandée	Surcharge ponctuelle des URLs configurées sur le partenaire.
`metadata`	object/null	Non	Objet JSON libre	Données de rapprochement interne du partenaire.

Exemple de payload standard

{
  "merchant_reference": "CMD-20260729-001",
  "amount": 12500,
  "description": "Vente de chaussure",
  "customer_phone": "22891390850",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

Réponses possibles

HTTP	Code applicatif	Cas
`201`	-	Session créée.
`401`	`authentication_failed`	Signature invalide.
`403`	`authorization_failed`	IP ou partenaire non autorisé.
`409`	`duplicate_merchant_reference`	Référence marchand déjà utilisée.
`422`	`validation_error`	Champ manquant ou invalide.

Exemple de réponse 201

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_url": "https://pay.solimi.co/checkout/CHK-20260729-8F2A91",
  "amount": 12500,
  "currency": "XOF",
  "description": "Vente de chaussure",
  "status": "OPEN",
  "expires_at": "2026-07-29T12:30:00Z"
}

GET/v1/checkout/sessions/{reference}

HMAC

Mode 2 - Page de paiement hébergée. Consulte le statut d'une session checkout créée par le partenaire.

Headers obligatoires

Header	Rôle	Format / valeur
`x-api-key`	Identifie le partenaire.	Clé API fournie par SOLIMI.
`x-timestamp`	Protection anti-rejeu.	Timestamp Unix en secondes, tolérance 300s.
`x-signature`	Authentifie la requête.	HMAC SHA-256 hex de `timestamp`, car le body est vide.

Payload

Aucun body requis.

Réponses possibles

HTTP	Code applicatif	Cas
`200`	-	Statut de la session retourné.
`401`	`authentication_failed`	Signature invalide ou headers absents.
`403`	`authorization_failed`	IP ou partenaire non autorisé.
`404`	`not_found`	Session introuvable pour ce partenaire.

Exemple de réponse 200

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Vente de chaussure",
  "status": "payment_initiated",
  "selected_payment_type": "mobile_money",
  "selected_provider": "mixx",
  "provider_payment_url": null,
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

POST/checkout/v1/sessions/{reference}/pay

Checkout public

Route interne de la page hébergée. Déclenche le paiement choisi par le client sur la page checkout SOLIMI.

Headers

content-type: application/json. Cette route est appelée par la page checkout, elle ne demande pas de signature HMAC partenaire.

Payload et validations

Champ	Type	Obligatoire	Valeurs / regex	Rôle
`payment_type`	enum	Oui	`mobile_money`, `bank_card`, `solimi_card`	Moyen choisi par le client.
`provider`	enum/null	Oui si mobile money	`mixx`, `moov_money`, `bank_card`	Provider technique.
`customer_phone`	string/null	Oui sauf carte bancaire	`^\+?[0-9]{8,20}$`	Numéro client ou support d'identification.
`card_id`	string/null	Oui si carte virtuelle SOLIMI	`^\d{8}$`	Carte ID de 8 chiffres visible sur la carte virtuelle SOLIMI. Différent du numéro complet à 16 chiffres.

Aide client. Le client retrouve le card_id dans l'application SOLIMI, sur sa carte virtuelle, au niveau du libellé Carte ID. Cette valeur sert uniquement à identifier la carte virtuelle SOLIMI à débiter après validation.

Exemples de payload

{
  "payment_type": "bank_card",
  "provider": "bank_card"
}

{
  "payment_type": "mobile_money",
  "provider": "mixx",
  "customer_phone": "22891390850"
}

Exemple de réponse 200

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Vente de chaussure",
  "status": "PROCESSING",
  "selected_payment_type": "bank_card",
  "selected_provider": "bank_card",
  "provider_payment_url": "https://secure-gateway.example/pay/abc123",
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

L'URL webhook du partenaire est configurée par l'équipe SOLIMI dans la plateforme interne. Il n'existe plus d'endpoint public permettant au partenaire de créer ou modifier lui-même son webhook.

Webhooks

SOLIMI appelle votre endpoint webhook lorsqu'un paiement change d'état. Votre serveur doit répondre avec un statut HTTP 2xx. En cas d'échec, SOLIMI relance selon les délais: 30s, 60s, 300s, 900s.

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

Événements

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

Vérification 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 à jour la commande/facture du partenaire ici.
    # Exemple: payment.success => commande payée.

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

La vérification est volontairement simple: le header x-solimi-signature contient directement le secret webhook. Gardez ce secret côté serveur uniquement.

Erreurs

Les erreurs sont retournées au format JSON suivant.

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

HTTP	Code	Action recommandée
401	`authentication_failed`	Vérifier les headers HMAC, le timestamp et la signature.
403	`authorization_failed`	Vérifier l'IP autorisée, l'état de la clé API et du partenaire.
404	`not_found`	Vérifier la référence de paiement ou la route appelée.
409	`idempotency_conflict`	Réutiliser une meme clé uniquement pour la meme requête logique.
429	`api_key_temporarily_locked`	Attendre la fin du blocage temporaire, puis vérifier le secret API et le calcul HMAC avant de relancer les appels.
422	`validation_error`	Corriger les champs invalides dans le payload.

Collection Postman

La collection Postman SOLIMI regroupe les requêtes prêtes à tester pour les endpoints publics: création de paiement, création de session checkout, consultation de statut et moyens de paiement disponibles. Elle aide les équipes techniques à démarrer rapidement sans reconstruire les headers et payloads depuis zéro.

Comment l'utiliser

Téléchargez le fichier JSON de collection.
Dans Postman, cliquez sur Import, puis sélectionnez le fichier téléchargé.
Renseignez les variables base_url, api_key, api_secret et les valeurs de test.
Lancez les requêtes de la section 03 - Payments pour valider l'intégration.
Utilisez la section 05 - Sandbox Simulator pour simuler les retours succès, refus, échec ou expiration.

Fichier disponible

Format JSON compatible avec Postman. Le fichier contient les scripts nécessaires pour calculer les headers HMAC, ajouter automatiquement l'idempotency key sur les paiements et tester le simulateur sandbox pendant la recette.

Télécharger la collection Postman

POST/v1/payments/coris-money/otp

HMAC

Mode 1 - API directe. Vérifie le numéro Coris Money et déclenche l'envoi du code OTP avant l'initiation du paiement.

Payload

Champ	Type	Obligatoire	Format	Rôle
`phone`	string	Oui	`^\+?[0-9]{8,20}$`	Numéro du client Coris Money.

Réponses possibles

HTTP	Code	Cas	Exemple
`200`	`200`	OTP envoyé.	`{"code":"200","message":"OTP envoyé"}`
`404`	`404`	Aucun compte Coris Money associé au numéro.	`{"code":"404","message":"Aucun compte associé à ce numéro."}`
`502`	`500`	Erreur provider Coris Money.	`{"code":"500","message":"Une erreur s'est produite. Veuillez réessayer plus tard."}`

Exemple

{
  "phone": "22891390850"
}

La collection ne contient pas vos secrets. Les valeurs sensibles doivent être renseignées dans vos variables d'environnement Postman et ne doivent pas être partagées publiquement.

Checklist de mise en production

Stocker la clé API et le secret API dans un coffre de secrets côté serveur.
Signer toutes les requêtes avec le corps exact envoyé a SOLIMI.
Utiliser une cle d'idempotence unique pour chaque paiement marchand.
Vérifier les webhooks en comparant x-solimi-signature au secret webhook configuré.
Prevoir le polling de statut en secours si un webhook est indisponible.
Fournir à SOLIMI les adresses IP publiques de vos serveurs.
Tester les cas succès, échec, 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 direct payments, create hosted checkout sessions, check status, list available payment methods and receive signed webhook notifications.

REST JSON HMAC-SHA256 Idempotency Secured webhooks

Download Postman collection

Authentication Every request is signed with your API secret.

Currency Collection transactions are expressed in XOF.

Channels Mobile money, bank card and SOLIMI virtual 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
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.

Sandbox simulation. During integration, sandbox payments do not always trigger a real debit through Mobile Money operators or SOLIMI virtual cards. SOLIMI therefore provides a provider-return simulator to reproduce SUCCESS, DECLINED, FAILED and TIMEOUT scenarios. The simulator is used after creating a payment, with the SOLIMI reference returned by the API. It updates the payment status and triggers the partner webhook like a real provider callback. This feature is sandbox-only and is not available in production.

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.

Abuse attempt protection

If a valid API key is repeatedly used with invalid signatures or timestamps, SOLIMI temporarily blocks authentication for that key to limit brute-force attempts against the API secret.

The temporary block returns 429 api_key_temporarily_locked.
The standard lock duration is 15 minutes.
Calls from unauthorized IP addresses still return 403 authorization_failed.

0. Choose an integration mode

SOLIMI provides two ways to collect a payment. The right choice depends on how much control you want over the customer experience.

1. Direct API

Your platform displays its own payment forms, collects the phone number or SOLIMI virtual card, then calls the SOLIMI API directly.

Main endpoint: POST /v1/payments/request.
Status lookup: GET /v1/payments/status/{reference}.
Best when you already control your own payment interface.

2. Hosted payment page

Your backend creates a checkout session. SOLIMI returns a payment link; the customer is redirected to a SOLIMI page where they choose Mixx, Moov Money, bank card or SOLIMI virtual card.

Create: POST /v1/checkout/sessions.
Status lookup: GET /v1/checkout/sessions/{reference}.
Best for fast integration without building the payment method selection interface.

1. Direct API

This mode is the integration where your own application controls the payment interface. Your backend calls POST /v1/payments/request directly, then follows the status with GET /v1/payments/status/{reference} and webhooks.

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

Mobile money

payment_type = mobile_money

Requires provider: mixx, coris_money or moov_money.

SOLIMI virtual card

payment_type = solimi_card

Requires an 8-digit card_id.

Bank card

payment_type = bank_card

Returns a provider_payment_url to redirect the customer to Visa/Mastercard.

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.

2. Hosted SOLIMI payment page

This mode is the integration where SOLIMI hosts the payment method selection interface. The partner does not build the payment screen: it creates a session, receives a link, then redirects the customer.

Hosted checkout lets the partner call a single API to create a payment session. SOLIMI then returns a payment_url to open on the customer side. On that page, the customer chooses Mixx, Moov Money, SOLIMI virtual card or bank card.

When to use mode 2

You want SOLIMI to host the payment method selection interface.
You do not want to integrate each provider separately in your application.
You want a simple web flow with redirection back to your website after payment.

Redirects

Success, failure and cancellation URLs can be configured on the partner profile by SOLIMI. The payload can also override them for a specific session, but this is not required in the standard flow.

Partner-side endpoints

POST `/v1/checkout/sessions`

Creates the payment session and returns the link to open for the customer.

Standard payload

{
  "merchant_reference": "CMD-20260729-001",
  "amount": 12500,
  "description": "Mandarin sale",
  "customer_phone": "22891390850",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

201 response

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_url": "https://pay.solimi.co/checkout/CHK-20260729-8F2A91",
  "amount": 12500,
  "currency": "XOF",
  "description": "Mandarin sale",
  "status": "created",
  "expires_at": "2026-07-29T12:30:00Z"
}

Possible errors: 401 authentication_failed, 403 authorization_failed, 409 duplicate_merchant_reference, 422 validation_error.

GET `/v1/checkout/sessions/{reference}`

Checks a checkout session status as a fallback to webhooks.

Payload

No body required. The request is still HMAC-signed with an empty body.

200 response

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Mandarin sale",
  "status": "payment_initiated",
  "selected_payment_type": "mobile_money",
  "selected_provider": "mixx",
  "provider_payment_url": null,
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

Possible errors: 401 authentication_failed, 403 authorization_failed, 404 not_found.

Recommended flow

Your backend creates a session with POST /v1/checkout/sessions.
You redirect the customer to the returned payment_url.
The customer chooses a payment method on SOLIMI Checkout.
SOLIMI executes the payment, updates the status and calls your webhook.
Your backend can call GET /v1/checkout/sessions/{reference} as a fallback.

Hosted checkout coexists with POST /v1/payments/request. Keep direct payment if you already control your own payment UI; use checkout if you want a ready-to-use SOLIMI payment journey.

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 provider for a solimi_card 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`, `bank_card`, `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.
`customer_first_name`	Customer first name.	string	No	Maximum 100 characters	`^.{0,100}$`	Stored for history, reconciliation and support. Not displayed on checkout.
`customer_last_name`	Customer last name.	string	No	Maximum 100 characters	`^.{0,100}$`	Stored for history, reconciliation and support. Not displayed on checkout.
`provider`	Mobile money operator.	enum string	Yes if `mobile_money`	Variable	`mixx`, `coris_money`, `moov_money`, `bank_card`	Required for `mobile_money`. For `bank_card`, the backend automatically applies `bank_card`.
`coris_country_code`	Coris Money country code fixed by SOLIMI.	string	No	1 to 10 characters	Always `228`	The backend automatically uses `228` to build the Coris Money withdrawal request.
`coris_otp`	OTP entered by the Coris Money customer.	string	Yes if `provider=coris_money`	1 to 20 characters	Example: `123456`	Sent to Coris Money to validate the debit.
`card_id`	Customer SOLIMI virtual card ID.	string	Yes if `solimi_card`	Exactly 8 digits	`^\d{8}$`	Visible in the SOLIMI app on the virtual card. Different from the full 16-digit card number.

Important for SOLIMI virtual cards. The card_id field is the 8-digit Card ID displayed on the virtual card in the SOLIMI app, for example 24924478. Do not send the full 16-digit virtual card number.

Coris Money is a 2-step flow. Before calling POST /v1/payments/request with provider=coris_money, first call POST /v1/payments/coris-money/otp with phone. SOLIMI checks the Coris Money account and sends the OTP. The customer then enters that OTP in coris_otp when creating the payment.

Conditional rules by payment type

`payment_type`	Required field	Fields not to send	Minimal example
`mobile_money`	`provider`	`card_id`	`{"payment_type":"mobile_money","provider":"mixx"}`
`mobile_money` + `coris_money`	`provider`, `coris_otp`	`card_id`	`{"payment_type":"mobile_money","provider":"coris_money","coris_otp":"123456"}`
`bank_card`	No conditional field	`card_id`	`{"payment_type":"bank_card"}`
`solimi_card`	`card_id`	`provider`	`{"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`, `bank_card`, `solimi_card`.
`provider`	Operator or technical provider.	enum or null	`mixx`, `coris_money`, `moov_money`, `bank_card`, 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.
`provider_payment_url`	External payment URL to open for bank card payments.	URL or null	Mainly returned when `payment_type=bank_card`.
`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.
`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`.
`provider_payment_url`	Bank card payment URL when available.	URL or null	Use it to redirect the customer to the secure Visa/Mastercard page.
`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 by integration mode

The endpoints below are grouped by usage: mode 1 direct API when you control your own payment interface, and mode 2 hosted page when you redirect the customer to SOLIMI Checkout. Partner endpoints 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

Mode 1 - Direct API. Creates a payment request from your own interface.

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`, `bank_card`, `solimi_card`	Collection channel.
`provider`	enum/null	Yes for mobile money	`mixx`, `moov_money`, `coris_money`, `bank_card`	Mobile money operator. For `bank_card`, the backend fills it automatically.
`coris_country_code`	string/null	No	Always `228`	Coris country code automatically fixed by the backend.
`coris_otp`	string/null	Yes for Coris Money	Max 20 characters	Coris Money OTP entered by the customer.
`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.
`customer_first_name`	string/null	No	Max 100 characters	First name stored for history and support.
`customer_last_name`	string/null	No	Max 100 characters	Last name stored for history and support.
`card_id`	string/null	Yes for SOLIMI virtual card	`^\d{8}$`	8-digit Card ID shown on the virtual card in the SOLIMI app. Do not send the full 16-digit card number.

SOLIMI virtual card. For payment_type = solimi_card, send the 8-digit card_id displayed in the SOLIMI app, not the full card number.

Payload example

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

Bank card payload example

{
  "merchant_reference": "ORDER-2026-0002",
  "payment_type": "bank_card",
  "amount": 25000,
  "description": "Order ORDER-2026-0002",
  "customer_phone": "22890112233",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

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",
  "provider_payment_url": null,
  "expires_at": "2026-06-19T21:00:00Z",
  "created_at": "2026-06-19T20:45:00Z"
}

GET/v1/payments/status/{reference}

HMAC

Mode 1 - Direct API. Returns the current status of a payment initiated through the direct API.

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",
  "payment_type": "mobile_money",
  "provider": "mixx",
  "amount": 25000,
  "currency": "XOF",
  "status": "SUCCESS",
  "provider_payment_url": null,
  "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/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`, `coris_money`, `moov_money`, `bank_card`, `solimi_card`	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": "mobile_money",
    "name": "Coris Money",
    "provider": "coris_money",
    "is_active": true
  },
  {
    "code": "moov_money",
    "name": "Moov Money",
    "provider": "moov_money",
    "is_active": true
  },
  {
    "code": "bank_card",
    "name": "Bank card",
    "provider": "bank_card",
    "is_active": true
  },
  {
    "code": "solimi_card",
    "name": "SOLIMI virtual card",
    "provider": null,
    "is_active": true
  }
]

POST/v1/checkout/sessions

HMAC + Idempotency-Key

Mode 2 - Hosted payment page. Creates a checkout session and returns the payment link to show to the customer.

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 duplicates on retries.	Unique per logical attempt.

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.
`amount`	integer	Yes	`^[1-9]\d*$`	Amount to collect in XOF.
`description`	string	Yes	Non-empty	Label shown to the customer.
`customer_email`	string/null	No	Valid email, max 255	Optional, used only for history/support. No automatic email is sent to the payer.
`customer_phone`	string/null	No	`^\+?[0-9]{8,20}$`	Prefill customer phone.
`customer_first_name`	string/null	No	Max 100 characters	Stored for history. Not displayed on the checkout page.
`customer_last_name`	string/null	No	Max 100 characters	Stored for history. Not displayed on the checkout page.
`currency`	string	No	`XOF`	Optional. Backend defaults to `XOF`.
`success_url`, `failure_url`, `cancel_url`	URL/null	No	HTTPS URL recommended	Optional override of URLs configured on the partner profile.
`metadata`	object/null	No	Free JSON object	Partner reconciliation data.

Standard payload example

{
  "merchant_reference": "CMD-20260729-001",
  "amount": 12500,
  "description": "Mandarin sale",
  "customer_phone": "22891390850",
  "customer_first_name": "Magloire",
  "customer_last_name": "ZOI"
}

Possible responses

HTTP	Application code	Case
`201`	-	Session created.
`401`	`authentication_failed`	Invalid signature.
`403`	`authorization_failed`	IP or partner not allowed.
`409`	`duplicate_merchant_reference`	Merchant reference already used.
`422`	`validation_error`	Missing or invalid field.

201 response example

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_url": "https://pay.solimi.co/checkout/CHK-20260729-8F2A91",
  "amount": 12500,
  "currency": "XOF",
  "description": "Mandarin sale",
  "status": "OPEN",
  "expires_at": "2026-07-29T12:30:00Z"
}

GET/v1/checkout/sessions/{reference}

HMAC

Mode 2 - Hosted payment page. Returns the status of a checkout session created by the partner.

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, 300s tolerance.
`x-signature`	Authenticates the request.	Hex HMAC SHA-256 of `timestamp`, because the body is empty.

Payload

No body required.

Possible responses

HTTP	Application code	Case
`200`	-	Session status returned.
`401`	`authentication_failed`	Invalid signature or missing headers.
`403`	`authorization_failed`	IP or partner not allowed.
`404`	`not_found`	Session not found for this partner.

200 response example

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Mandarin sale",
  "status": "payment_initiated",
  "selected_payment_type": "mobile_money",
  "selected_provider": "mixx",
  "provider_payment_url": null,
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

POST/checkout/v1/sessions/{reference}/pay

Public checkout

Internal hosted page route. Triggers the payment selected by the customer on the SOLIMI checkout page.

Headers

content-type: application/json. This route is called by the checkout page and does not require partner HMAC.

Payload and validations

Field	Type	Required	Values / regex	Purpose
`payment_type`	enum	Yes	`mobile_money`, `bank_card`, `solimi_card`	Payment method selected by the customer.
`provider`	enum/null	Yes for mobile money	`mixx`, `moov_money`, `bank_card`	Technical provider.
`customer_phone`	string/null	Yes except for bank card	`^\+?[0-9]{8,20}$`	Customer phone or identification helper.
`card_id`	string/null	Yes for SOLIMI virtual card	`^\d{8}$`	8-digit Card ID visible on the SOLIMI virtual card. Different from the full 16-digit card number.

Customer help. The customer can find the card_id in the SOLIMI app on the virtual card, next to the Card ID label. This value only identifies the SOLIMI virtual card to debit after customer approval.

Payload examples

{
  "payment_type": "bank_card",
  "provider": "bank_card"
}

{
  "payment_type": "mobile_money",
  "provider": "mixx",
  "customer_phone": "22891390850"
}

200 response example

{
  "checkout_reference": "CHK-20260729-8F2A91",
  "merchant_reference": "CMD-20260729-001",
  "payment_reference": "SOLPAY20260729881234",
  "amount": 12500,
  "currency": "XOF",
  "description": "Mandarin sale",
  "status": "PROCESSING",
  "selected_payment_type": "bank_card",
  "selected_provider": "bank_card",
  "provider_payment_url": "https://secure-gateway.example/pay/abc123",
  "expires_at": "2026-07-29T12:30:00Z",
  "completed_at": null,
  "cancelled_at": null
}

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.

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.
429	`api_key_temporarily_locked`	Wait until the temporary lock expires, then verify the API secret and HMAC calculation before retrying.
422	`validation_error`	Fix invalid fields in the payload.

Postman collection

The SOLIMI Postman collection bundles ready-to-run requests for the public endpoints: payment creation, checkout session creation, payment status lookup 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.
Use 05 - Sandbox Simulator to simulate success, decline, failure or expiration callbacks.

Available file

JSON format compatible with Postman. The collection includes scripts to compute HMAC headers and automatically add the idempotency key on payment requests, plus sandbox simulator requests for acceptance testing.

Download Postman collection

POST/v1/payments/coris-money/otp

HMAC

Mode 1 - Direct API. Checks the Coris Money number and sends the OTP before payment initiation.

Payload

Field	Type	Required	Format	Purpose
`phone`	string	Yes	`^\+?[0-9]{8,20}$`	Coris Money customer phone.

Possible responses

HTTP	Code	Case	Example
`200`	`200`	OTP sent.	`{"code":"200","message":"OTP envoyé"}`
`404`	`404`	No Coris Money account linked to the number.	`{"code":"404","message":"Aucun compte associé à ce numéro."}`
`502`	`500`	Coris Money provider error.	`{"code":"500","message":"Une erreur s'est produite. Veuillez réessayer plus tard."}`

Example

{
  "phone": "22891390850"
}

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

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'intégration SOLIMI pour marchands, fintechs et banques

Environnements et prérequis

Authentification HMAC

Headers obligatoires

Algorithme

Protection contre les tentatives abusives

Choisir son mode d'intégration

1. API directe

2. Page de paiement hébergée

1. API directe

Mobile money

Carte virtuelle SOLIMI

Carte bancaire

Cycle de vie

2. Page de paiement hébergée SOLIMI

Quand utiliser le mode 2

Redirections

Endpoints à intégrer côté partenaire

POST /v1/checkout/sessions

Payload standard

Réponse 201

GET /v1/checkout/sessions/{reference}

Payload

Réponse 200

Flux recommandé

Référence des payloads et validations

Headers de sécurité

PaymentRequestCreate - Création d'un paiement

Règles conditionnelles par type de paiement

PaymentRequestResponse - Réponse de création

PaymentStatusResponse - Suivi de paiement

Payloads webhook

Endpoints publics par mode d'intégration

GET/v1/health

Headers

Payload

Réponses possibles

Exemples d'appel

Exemple de réponse 200

POST/v1/payments/request

Headers obligatoires

Payload et validations

Exemple de payload

Exemple carte bancaire

Réponses possibles

Exemples d'appel

Exemple de réponse 201

GET/v1/payments/status/{reference}

Headers obligatoires

Parametres

Réponses possibles

Exemples d'appel

Exemple de réponse 200

GET/v1/payment-methods

Headers obligatoires

Payload

Champs de réponse

Réponses possibles

Exemples d'appel

Exemple de réponse 200

POST/v1/checkout/sessions

Headers obligatoires

Payload et validations

Exemple de payload standard

Réponses possibles

Exemple de réponse 201

GET/v1/checkout/sessions/{reference}

Headers obligatoires

Payload

Réponses possibles

Exemple de réponse 200

POST/checkout/v1/sessions/{reference}/pay

Headers

Payload et validations

Exemples de payload

Exemple de réponse 200

Webhooks

Événements

Vérification webhook FastAPI

Erreurs

POST `/v1/checkout/sessions`

GET `/v1/checkout/sessions/{reference}`

`PaymentRequestCreate` - Création d'un paiement

`PaymentRequestResponse` - Réponse de création

`PaymentStatusResponse` - Suivi de paiement

POST `/v1/checkout/sessions`

GET `/v1/checkout/sessions/{reference}`

`PaymentRequestCreate` - Payment creation

`PaymentRequestResponse` - Creation response

`PaymentStatusResponse` - Payment tracking