RayPlusGroup Logo RayPlusGroup Developer
Créer un compte

Connecter votre agent IA

Donnez à votre agent de codage (Claude Code, Cursor, Windsurf, VS Code) un accès direct à la documentation RayMoney, et faites-lui vérifier ses requêtes avant de les envoyer.

MCP v2024-11-05 Public & Lecture Seule Zéro clé requise pour la doc Streamable HTTP & SSE

Si vous intégrez RayMoney avec Claude Code, Cursor ou un autre agent, vous n'avez pas à lui copier-coller la documentation page par page. Le serveur MCP la lui expose en direct, dans le format structuré qu'il sait lire : il cherche au lieu de deviner, et il travaille toujours sur la version officielle à jour.

Il fait une deuxième chose, qui compte encore davantage : il relit et certifie la requête que votre agent s'apprête à envoyer. RayMoney déplace de l'argent réel sur les réseaux Mobile Money en Afrique de l'Ouest (Franc CFA), donc chaque appel mal formé ou erroné peut impacter la production.

Le serveur est public, en lecture seule pour la documentation, et ne demande aucune clé pour être interrogé.

PARCOURS D'INTÉGRATION RAPIDE

Par où commencer votre intégration ?

Quatre étapes pour connecter vos outils, tester en bac à sable et déployer vos premiers paiements réels en Afrique de l'Ouest.

Étape 1

1. Connecter votre agent

Une commande terminal pour Claude Code, Cursor ou VS Code : votre IA lit la doc en direct et valide vos schémas.

Installer le MCP
Étape 2

2. Clés & Activation

Inscrivez-vous sur client.rayplusmoney.com et validez votre KYC marchand pour obtenir vos clés API sans erreur 403.

Configuration des accès
Étape 3

3. Choisir le bon flux

Comparez Straight Payin (Push USSD), Redirect Checkout hébergé ou Liens de paiement partageables.

Explorer les 3 produits
Étape 4

4. Webhook & Signature

Configurez la seule source de vérité : vérification HMAC-SHA256, gestion de l'idempotence et retries.

Sécuriser le callback
GUIDE DE DÉMARRAGE — FONDAMENTAUX

Principes fondamentaux de l'écosystème

Comprendre comment circulent les fonds, comment s'articulent vos comptes marchands et quel mode d'intégration correspond le mieux à votre application.

1. L'argent circule dans deux sens

Toute l'infrastructure financière de RayMoney s'articule autour de deux mouvements cardinaux :

Encaisser (Pay-in)

Recevoir des fonds d'un client par Mobile Money (Wave, Orange, MTN, Moov) ou par carte bancaire VISA. L'argent crédite immédiatement le solde de votre compte marchand.

Reverser (Pay-out)

Envoyer des fonds à des tiers (livreurs, prestataires, salaires ou partenaires) directement vers leur portefeuille mobile ou compte bancaire. Débite instantanément votre solde disponible.

Un compte unique et temps réel
Ce que vous encaissez auprès de vos clients est immédiatement disponible pour être reversé par API Payouts, sans délai d'attente ni transfert intermédiaire de compte à compte.

2. Le compte Marchand est l'unité de base

Une entreprise cliente possède un compte marchand (identifié par son merchant_id ou storeId) et un jeu de clés d'API. Chaque magasin ou filiale dispose de son propre historique comptable et de ses webhooks dédiés.

Chaque requête API porte votre jeton d'authentification, et chaque transaction de paiement ou reversement génère un identifiant unique (reference) fourni par votre système pour garantir une traçabilité totale de bout en bout.

3. Trois façons d'encaisser selon votre cas d'usage

Une seule intégration technique donne accès à trois modes de collecte complémentaires :

Solution Expérience client Cas d'usage recommandé Endpoint API
Straight Payin
Push USSD Direct		 Le client reçoit directement une invite sur son écran de téléphone pour taper son code PIN Mobile Money. Aucune redirection web. Applications mobiles (iOS/Android), bornes interactives, tunnels d'achat optimisés pour une conversion maximale. POST /v1/payments/straight
Redirect Checkout
Page hébergée		 Redirection vers une page de paiement hébergée par RayMoney. Le client choisit son opérateur ou sa carte VISA, puis est redirigé vers votre site. Sites e-commerce (WooCommerce, Shopify, Prestashop, Next.js), abonnements et tunnels web universels. POST /v1/payments/redirect
Liens de Paiement
Partageable		 Génération d'une URL courte sécurisée à envoyer par WhatsApp, SMS ou email. Facturation client B2B, devis d'acompte, collectes d'événements, service client sans développeur dédié. POST /v1/payments/links

4. Tout est asynchrone : les Webhooks sont la source de vérité

Sur les réseaux de Mobile Money en Afrique, la confirmation définitive dépend de la saisie du code secret par l'utilisateur sur son propre terminal mobile. L'API retourne donc immédiatement un statut PENDING.

Dès que l'opérateur valide la transaction (généralement en moins de 2 secondes), RayMoney appelle instantanément votre URL de Webhook avec le statut final (SUCCESS ou FAILED), signée cryptographiquement avec votre clé secrète via l'en-tête X-RayMoney-Signature (HMAC-SHA256).

Idempotence stricte obligatoire
En cas de perte de réseau ou de timeout, RayMoney applique des retries automatiques sur vos webhooks avec backoff exponentiel. Votre endpoint de callback doit vérifier l'identifiant de transaction (reference) pour éviter tout double traitement de commande.

5. Cycle de vie d'une transaction (Cinématique & États)

Comprendre les transitions d'état entre votre backend, RayMoney et l'opérateur télécom :

┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Client Payeur│ │ Votre Backend │ │ RayMoney Cloud │ │ Opérateur Telco │ └──────┬───────┘ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ │── (1) Clique "Payer" ───>│ │ │ │ │── (2) POST /payments ─────>│ │ │ │ │── (3) Push USSD / Débit ──>│ │ │<── (4) HTTP 200 PENDING ───│ │ │ │ │ │ │<──────────────────────── (5) Invite PIN Mobile Money / SMS validation ────────────│ │── (6) Tape Code Secret ───────────────────────────────────────────────────────────>│ │ │ │ │ │ │ │<── (7) Accord Opérateur ───│ │ │<── (8) POST Webhook (HMAC)─│ │ │ │─── (9) HTTP 200 OK ───────>│ │ │<── (10) Accès Service ───│ │ │
Statut Description Action pour votre système
PENDING La demande est créée. En attente de saisie du PIN par l'utilisateur sur son téléphone. Afficher un spinner ou un écran d'attente. Ne pas livrer le service.
SUCCESS L'opérateur a débité le client et crédité votre compte marchand RayMoney. Vérifier la signature du webhook, marquer la commande comme payée et livrer.
FAILED Échec de la transaction (solde client insuffisant, code PIN erroné, annulation manuelle). Afficher l'erreur retournée et inviter le client à réessayer ou choisir un autre opérateur.
EXPIRED Le délai imparti pour valider l'USSD ou la session de checkout (généralement 5 min) a expiré. Annuler la session en cours et générer une nouvelle tentative de paiement.
Règle de sécurité absolue (Source de vérité)
Ne livrez jamais une commande sur la seule foi d'une redirection navigateur. Le retour de l'utilisateur sur votre page de succès ne prouve rien : il peut fermer son navigateur avant d'y arriver ou construire l'URL à la main. Attendez impérativement le Webhook signé HMAC-SHA256.
CONFIGURATION & ENVIRONNEMENTS

Configuration Développeur & Authentification

Comment vous authentifier, gérer vos environnements de test et intégrer en toute sécurité.

Environnements & Base URLs

Composant Base URL Officielle Authentification Rôle & Usage
Passerelle RayMoney (Paiements) https://app.rayplusmoney.com/
Endpoints : /pay/v01/...		 Apikey + Authorization: Bearer Transactions financières réelles en FCFA (XOF) : encaissements Mobile Money et déboursements.
Serveur MCP IA RayPlusGroup https://api.rayplusgroup.com/mcp Aucune clé (Public / Lecture seule) Fournit la doc en direct, les schémas JSON et valide vos charges utiles pour Claude Code, Cursor, VS Code.
Espace Client & Inscription Marchand https://client.rayplusmoney.com Email / Téléphone + Mot de passe Création de compte marchand (client.rayplusmoney.com/registration), validation KYC et obtention des clés API.
Création de compte & Clés API (Pas de console développeur dédiée)

Il n'existe pas actuellement de console développeur séparée. L'ouverture de compte et la gestion de vos accès se font exclusivement sur le portail client : client.rayplusmoney.com (ou inscription directe sur client.rayplusmoney.com/registration).
Une fois votre profil marchand validé par l'équipe conformité, vos identifiants d'API (Apikey et jeton d'application Bearer) vous sont délivrés pour autoriser vos transactions.

En-têtes d'autorisation RayMoney (2 Headers Obligatoires)

Tous les appels vers la passerelle de paiement RayMoney (app.rayplusmoney.com) nécessitent deux en-têtes simultanés : 

Apikey: live_pk_votre_cle_publique_marchand
Authorization: Bearer live_sk_votre_token_application_jwt
Content-Type: application/json
Accept: application/json

Rappel MCP : Le serveur MCP public pour l'assistance IA (https://api.rayplusgroup.com/mcp) est accessible en lecture seule sans authentification pour la consultation documentaire et la validation syntaxique de vos requêtes.

Créer un magasin dédié aux tests

Créez un magasin ou sous-compte dédié aux tests, séparé de vos magasins de production. Vos requêtes d'intégration en bac à sable utilisent les simulateurs des réseaux pour valider votre logique métier sans manipuler d'argent réel. Isolez ainsi les membres de votre équipe technique avec le rôle Développeur restreint au magasin de test.

Activer l'accès API & Résolution de l'erreur 403

Générer vos clés API ne suffit pas : l'accès à l'API est soumis à la validation réglementaire de votre profil entreprise (KYC/KYS). Tant que cette étape n'est pas validée, vos requêtes reçoivent une réponse HTTP 403 même si vos clés d'API sont formellement valides : 

{
  "id": "business_not_enabled_for_api_access",
  "message": "This business account is not enabled for API access"
}
Débloquer l'accès API en 1 étape
Si votre premier appel répond 403 alors que vos en-têtes sont corrects, votre entreprise doit valider son niveau 1 depuis le tableau de bord ou auprès du support (support@rayplusgroup.com). Dès validation, l'accès API est activé instantanément.

Idempotence des transactions (`reference` / `X-Idempotency-Key`)

Pour éviter tout double débit en cas de timeout réseau ou de retry côté client, chaque transaction d'encaissement ou de reversement doit comporter une référence unique générée par votre backend (ex: CMD-2026-0925-A1B2). Si une requête avec la même référence est renvoyée, RayMoney renvoie l'état existant sans créer de seconde opération.

LIMITES RÉSEAUX

Montants et Plafonds par Réseau (Zone UEMOA)

Limites réglementaires et techniques par transaction selon l'opérateur pour l'encaissement et le reversement.

Opérateur & Réseau Code ID Zone géographique Minimum Encaissement Minimum Reversement Montant Maximum
Wave 39 Côte d'Ivoire (CI), Sénégal (SN) 100 FCFA 100 FCFA 2 000 000 FCFA
Orange Money 16 CI, SN, Mali (ML), Burkina (BF) 100 FCFA 100 FCFA 2 000 000 FCFA
MTN Mobile Money 13 Côte d'Ivoire (CI), Bénin (BJ) 100 FCFA 100 FCFA 2 000 000 FCFA
Moov Money Africa 14 CI, Togo (TG), Burkina (BF) 100 FCFA 100 FCFA 2 000 000 FCFA
Free Money 15 Sénégal (SN) 100 FCFA 100 FCFA 1 500 000 FCFA
Carte VISA & Mastercard VISA International (Toutes banques) 500 FCFA 1 000 FCFA 5 000 000 FCFA
1

Choisir votre client

Une seule commande, celle de votre client. Nommez l'entrée rayplusgroup : ce nom devient le préfixe des outils dans votre agent, et les exemples de cette page en dépendent. 

claude mcp add --scope user --transport http rayplusgroup https://api.rayplusgroup.com/mcp
// Dans votre fichier .cursor/mcp.json :
{
  "mcpServers": {
    "rayplusgroup": {
      "type": "http",
      "url": "https://api.rayplusgroup.com/mcp"
    }
  }
}
// Dans votre fichier .vscode/mcp.json :
{
  "mcpServers": {
    "rayplusgroup": {
      "type": "http",
      "url": "https://api.rayplusgroup.com/mcp"
    }
  }
}
{
  "mcpServers": {
    "rayplusgroup": {
      "type": "http",
      "url": "https://api.rayplusgroup.com/mcp"
    }
  }
}
Endpoint HTTP : https://api.rayplusgroup.com/mcp
Transport : Streamable HTTP / SSE (JSON-RPC 2.0)
Aucune authentification requise pour interroger la documentation.
2

Vérifier que la connexion est faite

Demandez-le simplement à votre agent dans la conversation : 

Quels outils rayplusgroup as-tu ?

Il doit citer les six outils, dont search_docs et review. S'il n'en voit aucun, rechargez votre client : la plupart ne rejouent la connexion qu'au démarrage.

Si le doute persiste
Cette commande cURL interroge directement le serveur sans passer par votre client, et doit lister les six outils. Si elle répond et que votre agent ne voit toujours rien, le problème est dans la configuration de votre client : 
curl -s -X POST https://api.rayplusgroup.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
3

Lancer votre première intégration

Plutôt que de décrire votre besoin de zéro, utilisez l'un de nos prompts guidés : 

/mcp__rayplusgroup__integrer_paiement straight

Puis expliquez votre contexte dans le message suivant, par exemple : « Je veux encaisser par Wave et Orange Money sur mon application mobile Flutter ». L'agent appellera automatiquement search_docs, consultera get_endpoint et déroulera l'intégration.

Le prompt lui interdit formellement d'appeler l'API avant d'avoir passé sa requête à review, qui vérifie l'endpoint, l'authentification (Apikey & Token Bearer), le schéma et les règles spécifiques RayMoney. Vous n'avez rien à réclamer : tant qu'il reste des erreurs, aucun appel ne part. C'est aussi lui qui attrape ce que le schéma standard n'exprime pas, comme le montant entier multiple de 100 sans décimale, l'indicatif 225 sans '+', ou l'OTP obligatoire pour Orange Money (réseau 16).

Pour implémenter votre récepteur de webhook, le second prompt fait rédiger le contrôleur puis le valide rigoureusement : 

/mcp__rayplusgroup__implementer_webhook python
Paiements réels en Franc CFA
Sur les flux marchands en production, chaque transaction validée déplace de l'argent réel. Utilisez systématiquement l'outil review pour auditer votre charge utile avant toute émission.

L'adresse

Pour toute configuration manuelle, ou pour un client absent de la liste : 

https://api.rayplusgroup.com/mcp

MCP est un protocole ouvert : tout client qui parle HTTP fonctionne, en renseignant cette adresse comme serveur distant, sans authentification préalable pour la documentation.

Les 6 Outils Disponibles

Voici les capacités que le serveur expose directement à votre assistant IA :

Domaine Outil Ce qu'il fait
Documentation search_docs Recherche plein texte dans toute la documentation technique, codes d'erreur et guides.
Documentation get_example Exemples d'appel complets et testés en cURL, Python, JavaScript, TypeScript, PHP et Dart.
Documentation get_integration_checklist Checklist ordonnée étape par étape : encaissement direct, redirection web, OTP Orange, webhooks.
API Reference get_endpoint Définition exhaustive d'une opération : schéma JSON complet, headers, exemples de réponse et erreurs.
Vérification review Revue pré-envoi rigoureuse d'une requête : vérifie Apikey, indicatifs télécom, montant XOF, OTP.
Vérification validate_webhook Relit votre contrôleur de callback et pointe ce qui manque (idempotence, parsing custom_data, HTTP 200).

S'y ajoutent 5 ressources documentaires natives (matrice des réseaux, dictionnaire des sous-codes Code00 à Code18, spécifications du webhook), et deux prompts pré-configurés (integrer_paiement et implementer_webhook).

SERVEUR MCP — PROMPTS DÉDIÉS

Prompts Dédiés pour Agents IA

Le serveur MCP RayPlusGroup embarque deux prompts guidés pour assister pas à pas votre agent de codage (Claude Code, Cursor, Windsurf, VS Code) :

/integrer_paiement Prêt à l'emploi

Flux d'encaissement Mobile Money

Guider pas à pas votre agent pour intégrer le paiement direct (straight) ou hébergé (redirect). Force la consultation de la checklist, l'application des règles d'or RayMoney (montants XOF, indicatif 225, OTP Orange) et l'audit strict avec l'outil review avant tout appel.

Arguments : type_flux (straight/redirect), langage (python/js/php)
/implementer_webhook Prêt à l'emploi

Contrôleur de Webhook & Certification

Génère le récepteur de callback : vérification HMAC-SHA256, décompression résiliente de custom_data (dictionnaire ou liste), gestion d'idempotence et validation automatique via validate_webhook jusqu'à obtenir le score de 100/100.

Arguments : langage (python/javascript/php)
Comment utiliser un prompt MCP dans votre éditeur ?
Dans Claude Code ou Cursor, saisissez : /mcp__rayplusgroup__integrer_paiement ou dites à l'agent : « Utilise le prompt MCP RayMoney pour m'aider à intégrer le paiement Wave et Orange Money en Node.js ».

Ce qu'il ne fait pas

Le serveur MCP est en lecture seule pour la documentation. Il ne demande aucune clé secrète marchande, n'en stocke aucune, et n'émet aucun appel vers les comptes bancaires ou wallets en votre nom.

C'est votre agent, exécuté sur votre propre machine avec vos clés déclarées dans vos variables d'environnement, qui appelle directement la passerelle de paiement RayMoney.

La lecture seule élimine le risque de manipulation externe : le serveur MCP renvoie des spécifications techniques et valide la conformité syntaxique et métier de vos charges utiles.

PRODUITS & API — OPÉRATEURS

Réseaux & Opérateurs Mobile Money

RayMoney agrège directement les principaux opérateurs télécoms et passerelles de paiement d'Afrique de l'Ouest (UEMOA). Lors de chaque initiation de paiement, renseignez l'identifiant numérique network correspondant dans le corps de votre requête.

Opérateur Pays ID Opérateur / Réseau (network) OTP Requis Montant min / max Cinématique de validation
Wave Wave CI / SN Côte d'Ivoire, Sénégal 39 Non 100 à 2 000 000 XOF Push USSD instantané ou Deep Link dans l'application Wave du client.
Orange Money Orange Money CI Côte d'Ivoire 16 OUI (Obligatoire) 100 à 1 500 000 XOF Le client compose impérativement #144*82# pour générer son code OTP temporaire à 4 chiffres.
MTN MoMo MTN MoMo CI Côte d'Ivoire 13 Non 100 à 2 000 000 XOF Notification push interactive USSD sur le téléphone du client pour saisie de son code secret.
Moov Money Moov Money CI Côte d'Ivoire 14 Non 100 à 2 000 000 XOF Push USSD interactif avec validation par code PIN confidentiel Moov.
Free Money Free Money SN Sénégal 15 Non 100 à 1 000 000 XOF Validation push USSD sur le réseau Free Sénégal.
VISAMastercard Cartes VISA & Mastercard International Redirect Checkout 3D-Secure Selon plafond émetteur Redirection vers page de paiement bancaire 3DS avec validation OTP SMS bancaire.
Règle stricte sur le format du numéro de téléphone (customer)
Le numéro de téléphone du client doit obligatoirement respecter le format international numérique sans le préfixe '+' et sans '00'.
Pour la Côte d'Ivoire (10 chiffres) : 2250708674556. N'envoyez jamais +225... ni 22500... (rejet immédiat).
Estimation Dynamique des Frais (Ne rien coder en dur)
Les commissions et frais de transaction ne doivent jamais être codés en dur dans vos applications (sites web, backends ou mobiles).
RayMoney met à disposition une API dédiée pour calculer et estimer dynamiquement les frais en temps réel selon le réseau, le volume et le profil marchand. Récupérez toujours les frais en direct via l'API ou consultez votre tableau de bord marchand.
PRODUITS & API — ENCAISSEMENT DIRECT

Straight Payin (Encaissement Direct)

Le mode Straight Payin initie un encaissement direct sans redirection. Votre application ou votre backend transmet le numéro de téléphone, l'opérateur et le montant, et RayMoney déclenche immédiatement le push USSD chez le client.

POST https://app.rayplusmoney.com/pay/v01/straight/checkout-invoice/create

En-têtes HTTP Requis

En-tête Valeur attendue Description
Content-Type application/json Format d'encodage du corps de la requête.
Accept application/json Format de réponse attendu.
Apikey live_pk_... Votre clé publique marchande RayMoney (identifie l'application).
Authorization Bearer live_sk_... Jeton d'autorisation secret Bearer fourni par RayMoney.

Exemple de Requête Complète (Wave CI - Réseau 39)

curl -s -X POST https://app.rayplusmoney.com/pay/v01/straight/checkout-invoice/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Apikey: live_pk_votre_cle" \
  -H "Authorization: Bearer live_sk_votre_token" \
  -d '{
    "commande": {
      "invoice": {
        "items": [
          {
            "name": "Recharge Solde Compte",
            "quantity": 1,
            "unit_price": 5000,
            "total_price": 5000
          }
        ],
        "total_amount": 5000,
        "devise": "XOF",
        "customer": "2250708674556",
        "network": 39
      },
      "store": {
        "name": "Ma Boutique",
        "website_url": "https://votresite.com"
      },
      "actions": {
        "cancel_url": "https://votresite.com/cancel",
        "return_url": "https://votresite.com/success",
        "callback_url": "https://votresite.com/webhooks/raymoney",
        "callback_url_method": "post_json"
      },
      "custom_data": {
        "transaction_id": 1727361234567,
        "order_id": "CMD-89421",
        "user_id": 4821
      }
    }
  }'
import httpx

payload = {
    "commande": {
        "invoice": {
            "items": [{"name": "Recharge Solde", "quantity": 1, "unit_price": 5000, "total_price": 5000}],
            "total_amount": 5000,
            "devise": "XOF",
            "customer": "2250708674556",
            "network": 39  # 39=Wave, 16=Orange Money (requiert 'otp'), 13=MTN, 14=Moov
        },
        "store": {
            "name": "Ma Boutique",
            "website_url": "https://votresite.com"
        },
        "actions": {
            "cancel_url": "https://votresite.com/cancel",
            "return_url": "https://votresite.com/success",
            "callback_url": "https://votresite.com/webhooks/raymoney",
            "callback_url_method": "post_json"
        },
        "custom_data": {"order_id": "CMD-89421"}
    }
}

headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Apikey": "live_pk_votre_cle",
    "Authorization": "Bearer live_sk_votre_token"
}

with httpx.Client() as client:
    response = client.post("https://app.rayplusmoney.com/pay/v01/straight/checkout-invoice/create", json=payload, headers=headers)
    print(response.json())
const axios = require('axios');

async function initierPaiementDirect() {
  const payload = {
    commande: {
      invoice: {
        items: [{ name: "Abonnement Service", quantity: 1, unit_price: 5000, total_price: 5000 }],
        total_amount: 5000,
        devise: "XOF",
        customer: "2250708674556",
        network: 39
      },
      store: {
        name: "Ma Boutique",
        website_url: "https://votresite.com"
      },
      actions: {
        cancel_url: "https://votresite.com/cancel",
        return_url: "https://votresite.com/success",
        callback_url: "https://votresite.com/webhooks/raymoney",
        callback_url_method: "post_json"
      },
      custom_data: { order_id: "CMD-89421" }
    }
  };

  const res = await axios.post('https://app.rayplusmoney.com/pay/v01/straight/checkout-invoice/create', payload, {
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Apikey': 'live_pk_votre_cle',
      'Authorization': 'Bearer live_sk_votre_token'
    }
  });

  console.log('Résultat:', res.data);
}
PRODUITS & API — PAGE SÉCURISÉE

Redirect Checkout (Page Hébergée)

Idéal si vous préférez déléguer l'affichage du choix de l'opérateur et la saisie de l'OTP à RayMoney. Cette API génère une URL de redirection où votre client choisit son mode de paiement sur une interface responsive sécurisée.

POST https://app.rayplusmoney.com/pay/v01/redirect/checkout-invoice/create
URLs de retour utilisateur vs Callback serveur
• return_url : URL de votre site où le client est renvoyé en cas de succès.
• cancel_url : URL de votre site où le client revient s'il clique sur Annuler.
• callback_url : Notification serveur à serveur déclenchée par RayMoney dès validation effective des fonds (ne jamais se fier uniquement au retour navigateur pour délivrer le service).

Réponse Type (Redirection Client)

{
  "response_code": "00",
  "response_text": "Success",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "redirect_url": "https://app.rayplusmoney.com/pay/v01/redirect/checkout-invoice/pay?token=eyJ0eXAiOiJK...",
  "description": "Operation successfully"
}
PRODUITS & API — WEBHOOKS

Webhooks & Traitement des Callbacks

Dès qu'une transaction est confirmée ou rejetée par l'opérateur télécom, les serveurs RayMoney envoient une requête HTTP POST avec le détail du statut au format JSON vers votre actions.callback_url.

Format de la Charge Utile Reçue

{
  "transaction_id": 1727361234567,
  "status": "completed",
  "response_code": "00",
  "response_text": "Paiement effectue avec succes",
  "amount": 5000,
  "devise": "XOF",
  "customer": "2250708674556",
  "custom_data": [
    {"keyof_customdata": "order_id", "valueof_customdata": "CMD-89421"},
    {"keyof_customdata": "user_id", "valueof_customdata": "4821"}
  ]
}

🛡️ Les 5 Piliers d'un Webhook Sécurisé

  • 1. Réponse HTTP 200 immédiate : Répondez toujours status: 200 avec {"status": "ok"}. Tout code d'erreur ou délai de réponse > 5s entraînera des réessais automatiques.
  • 2. Contrôle rigoureux du succès : Validez la commande si et seulement si response_code == "00" OU status == "completed".
  • 3. Idempotence indispensable : Vérifiez dans votre base si la commande est déjà marquée comme payée avant de déclencher la livraison (évite les doubles crédits en cas de rejeu réseau).
  • 4. Décompression résiliente de custom_data : En test, RayMoney peut renvoyer un dictionnaire {"uid": "..."} ; en production, une liste d'objets [{"keyof_customdata": "uid", "valueof_customdata": "..."}]. Votre code doit impérativement supporter les deux formats.
  • 5. Ordre de lookup de la transaction : Récupérez la commande en base selon l'ordre de priorité officiel : 1. custom_data.uid (UUID interne), 2. custom_data.ref ou external_id, 3. transaction_id RayMoney.

Vérification de la Signature Cryptographique (HMAC-SHA256)

Pour vous prémunir des faux callbacks forgés par un tiers malveillant, RayMoney signe chaque webhook avec votre clé secrète marchand dans l'en-tête HTTP X-RayMoney-Signature sous la forme :
X-RayMoney-Signature: t=1727361234,v1=a1b2c3d4e5f6...

Voici l'implémentation standard recommandée en Python et Node.js : 

import hmac, hashlib, time

def verifier_signature_raymoney(raw_body: bytes, header_sig: str, secret_key: str) -> bool:
    try:
        # Extraire le timestamp t et la signature v1
        parts = dict(item.split("=") for item in header_sig.split(","))
        timestamp = int(parts.get("t", 0))
        received_sig = parts.get("v1", "")

        # 1. Protection anti-rejeu (tolérance 5 minutes)
        if abs(time.time() - timestamp) > 300:
            return False

        # 2. Calcul du HMAC sur "timestamp.corps_brut"
        payload_to_sign = f"{timestamp}.".encode("utf-8") + raw_body
        expected_sig = hmac.new(
            secret_key.encode("utf-8"),
            payload_to_sign,
            hashlib.sha256
        ).hexdigest()

        # 3. Comparaison en temps constant pour contrer les timing attacks
        return hmac.compare_digest(expected_sig, received_sig)
    except Exception:
        return False
PRODUITS & API — PAYOUTS

Payouts & Déboursements (Envois de Fonds)

L'API Payout permet d'effectuer des virements automatisés depuis votre balance marchande RayMoney directement vers le compte Mobile Money d'un bénéficiaire (chauffeurs, prestataires, remboursements clients).

POST https://app.rayplusmoney.com/pay/v01/straight/payout 
curl -s -X POST https://app.rayplusmoney.com/pay/v01/straight/payout \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Apikey: live_pk_votre_cle" \
  -H "Authorization: Bearer live_sk_votre_token" \
  -d '{
    "commande": {
      "amount": 25000,
      "customer": "2250700000000",
      "network": 39,
      "custom_data": {
        "transaction_id": 1727361234567,
        "payout_ref": "VIR-2026-092",
        "beneficiary_id": "DRIVER-442"
      },
      "callback_url": "https://votresite.com/webhooks/payout",
      "callback_url_method": "post_json",
      "top_up_wallet": 0
    }
  }'
PRODUITS & API — STATUT & CONFIRMATION

Check Status — Vérification de l'État d'une Facture

En complément du webhook (qui reste la source de vérité), cet endpoint sert de filet de sécurité et de réconciliation : si votre serveur n'a pas reçu le callback (coupure réseau, indisponibilité), vous pouvez interroger directement RayMoney pour connaître l'état réel de la transaction.

GET https://app.rayplusmoney.com/pay/v01/redirect/checkout-invoice/confirm?invoiceToken=<token> 
curl -s -X GET "https://app.rayplusmoney.com/pay/v01/redirect/checkout-invoice/confirm?invoiceToken=rm_token_xyz_abc123" \
  -H "Accept: application/json" \
  -H "Apikey: live_pk_votre_cle" \
  -H "Authorization: Bearer live_sk_votre_token"

Réponse Type & États Possibles

{
  "response_code": "00",
  "description": "completed",
  "status": "completed"
}
Valeur description / status Signification Action Recommandée
completed Paiement confirmé La transaction est bien payée côté opérateur. Traiter comme un callback de succès et créditer le client.
notcompleted Paiement échoué / annulé La transaction a été rejetée, annulée ou a expiré. Ne pas délivrer le service.
pending En attente de confirmation Le client n'a pas encore validé le prompt USSD ou le réseau télécom traite encore la requête.
PRODUITS & API — LIENS DE PAIEMENT

Liens de Paiement Partageables

Bientôt disponible par API

Générez des liens de paiement courts et sécurisés à envoyer par WhatsApp, SMS ou email pour vos factures, acomptes et collectes.

Disponibilité actuelle : La création de liens de paiement est active dès aujourd'hui directement depuis votre espace client sur client.rayplusmoney.com.
L'endpoint API REST automatisé (POST /pay/v01/payment-links) pour la génération programmatique est actuellement en cours de développement et sera ouvert très prochainement.

PRODUITS & API — CARTE BANCAIRE

Carte VISA Prépayée RayMoney

Bientôt disponible par API

Émission de cartes bancaires VISA physiques et virtuelles internationales co-brandées UBA pour vos collaborateurs, chauffeurs ou clients.

Disponibilité actuelle : Les cartes VISA RayMoney sont actives pour les retraits GAB et achats TPE/Internet dans le monde entier. Les commandes de cartes et le rechargement de solde se font via l'application mobile et le guichet marchand.
L'API d'émission programmatique de cartes (Card Issuing & Instant Top-up API) sera disponible très prochainement pour les partenaires agréés.

PRODUITS & API — TERMINAUX & PROXIMITÉ

Points Relais & Terminaux Physiques (Soundbox / TPE)

Bientôt disponible par API

Boîtiers connectés avec confirmation vocale instantanée du paiement au comptoir (Soundbox) et TPE de caisse pour points de vente physiques.

Disponibilité actuelle : Le réseau physique de Points Relais et les boîtiers Soundbox sont déployés chez nos commerçants partenaires en agence.
L'API de couplage et de déclenchement d'encaissement sur terminal physique (POST /pay/v01/devices/soundbox/push) est en cours de finalisation et sera documentée prochainement.

PRODUITS & API — CODES DE RETOUR

Codes d'Erreur & Sous-Codes RayMoney

Voici le dictionnaire officiel des sous-codes renvoyés par RayMoney lors des retours de statut ou dans les réponses de webhook, pour afficher un message clair et compréhensible à vos utilisateurs :

Code d'Erreur Signification Officielle Détail & Cause Action Recommandée
Code00 Échec d'authentification Clé API (Apikey) ou Token Bearer manquant ou invalide. Vérifier les variables d'environnement RAYMONEY_KEY et RAYMONEY_TOKEN.
Code01 Compte inactif Le compte marchand n'est pas activé pour les encaissements. Contacter le support RayPlusGroup ou vérifier l'activation sur client.rayplusmoney.com.
Code02 Montant invalide Le montant doit être un entier strict entre 100 et 1 000 000 XOF (pas de centimes). S'assurer que total_amount est un entier ≥ 100 sans décimale.
Code03 Adresse IP non autorisée L'adresse IP de votre serveur n'est pas autorisée par la passerelle. Enregistrer l'adresse IP publique de votre serveur dans votre espace client sur client.rayplusmoney.com.
Code04 Erreur traitement passerelle Erreur interne lors du traitement par la passerelle de paiement. Vérifier le payload JSON ou réinterroger l'API avec un délai de retry.
Code05 / Code06 Erreur d'envoi opérateur Échec de transmission de la requête à l'opérateur télécom distant. L'opérateur distant subit des lenteurs ; réessayez avec un backoff exponentiel.
Code07 Aucun opérateur configuré Aucun réseau Mobile Money actif pour cette application marchande. Activer les opérateurs partenaires (Wave, Orange, MTN, Moov) dans votre espace client client.rayplusmoney.com.
Code08 Données saisies invalides Format du numéro de téléphone ou montant non conforme. Vérifier le numéro (indicatif 225 sans '+' ni '0' initial) et le montant.
Code09 Erreur API temporaire Indisponibilité temporaire de l'infrastructure de paiement. Réessayer après quelques instants.
Code10 Signature manquante Signature de sécurité absente dans l'en-tête de la requête. Transmettre l'intégralité des en-têtes de sécurité requis.
Code11 Signature invalide La signature HMAC de la requête ne correspond pas. Vérifier la clé secrète marchand utilisée pour le calcul du hash.
Code12 / Code13 Méthode non autorisée Méthode HTTP d'appel invalide ou interdite sur cet endpoint. Vérifier le verbe HTTP (POST pour l'initiation, GET pour confirm).
Code14 Portefeuille invalide Identifiants du portefeuille ou wallet cible incorrects. Vérifier les coordonnées du compte destinataire.
Code15 Code OTP incorrect Le code d'autorisation temporaire Orange Money (#144*82#) est erroné. Inviter le client à ressaisir soigneusement le code reçu.
Code16 Code OTP expiré Le code OTP a dépassé sa durée de validité (généralement 15 minutes). Le client doit recomposer #144*82# pour obtenir un nouveau code.
Code17 Montant OTP incorrect Le montant généré lors de l'OTP ne correspond pas au montant facturé. Générer l'OTP avec le montant exact de la commande.
Code18 Solde insuffisant Le solde du compte Mobile Money du client est insuffisant. Inviter le client à recharger son compte Mobile Money et réinitier.

Tester le serveur MCP en direct

Testez les réponses du serveur MCP directement depuis votre navigateur :

Console d'interrogation MCP
En direct
mcp-client @ rayplusgroup / tools/call 
Sélectionnez un outil ci-dessus et cliquez sur « Exécuter » pour voir la réponse du serveur MCP en temps réel...