Documentation API MyPaie

Intégrez les paiements Orange Money et Carte Bancaire en quelques minutes.

Orange Money

Paiement mobile pour 7 pays d'Afrique de l'Ouest

Carte Bancaire

Visa & Mastercard via Ngenius (Orabank)

URL de base

Sandbox (test)

https://devs.mypaie.tech/api/v1

Production

https://devs.mypaie.tech/api/v1

Authentification

Toutes les requêtes API doivent inclure votre clé API dans le header.

Header HTTP

X-API-Key: pk_test_votre_cle_publique

Important : Ne partagez jamais votre clé secrète (sk_). Utilisez uniquement la clé publique (pk_) côté client.

Démarrage rapide

Effectuez votre premier paiement en 3 étapes :

1

Créez une session de paiement

Appelez l'API pour créer une session de checkout

cURL

curl -X POST https://devs.mypaie.tech/api/v1/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_test_xxx" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "description": "Commande #123"
  }'

2

Redirigez le client

Utilisez l'URL de checkout retournée

{
  "success": true,
  "data": {
    "session_id": "PAY_20260110_ABC123",
    "checkout_url": "https://devs.mypaie.tech/pay/PAY_20260110_ABC123",
    "amount": 5000,
    "currency": "XOF"
  }
}

3

Recevez la notification

Configurez votre webhook pour être notifié du résultat du paiement.

POST /checkout/sessions

Créer une session de checkout

Crée une session de paiement hébergée. Le client sera redirigé vers la page MyPaie pour choisir son moyen de paiement.

Paramètres

Paramètre	Type	Description
`amount` *	integer	Montant en unité monétaire (ex: 5000 pour 5000 XOF)
`currency` *	string	Code devise : `XOF` ou `XAF`
`description`	string	Description du paiement
`success_url`	string	URL de redirection après succès
`cancel_url`	string	URL de redirection si annulation
`customer_email`	string	Email du client
`metadata`	object	Données personnalisées (order_id, etc.)

Exemple de requête

curl -X POST https://devs.mypaie.tech/api/v1/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_test_xxx" \
  -d '{
    "amount": 15000,
    "currency": "XOF",
    "description": "Commande #12345",
    "success_url": "https://monsite.com/success",
    "cancel_url": "https://monsite.com/cancel",
    "customer_email": "client@email.com",
    "metadata": {"order_id": "12345"}
  }'

Réponse

{
  "success": true,
  "message": "Session de checkout créée",
  "data": {
    "session_id": "PAY_20260110_ABC12345",
    "checkout_url": "https://devs.mypaie.tech/pay/PAY_20260110_ABC12345",
    "amount": 15000,
    "currency": "XOF",
    "expires_at": "2026-01-10T01:30:00Z"
  }
}

POST /payments/initiate

Initier un paiement direct

Initie un paiement directement avec un moyen de paiement spécifié (sans page hébergée).

Paramètres communs

Paramètre	Type	Description
`amount` *	integer	Montant en centimes XOF (ex: 5000)
`currency` *	string	`XOF` ou `XAF`
`payment_method` *	string	`orange_money` ou `card`
`description` *	string	Description du paiement
`phone`	string	Requis si `orange_money`. Format `+22370XXXXXX`
`customer_email`	string	Email du client (recommandé)
`customer_name`	string	Nom complet du client
`return_url`	string	URL de redirection après succès
`cancel_url`	string	URL de redirection si annulation
`metadata`	object	Données personnalisées (order_id, etc.)

Réponse

{
  "success": true,
  "data": {
    "transaction_id": 123,
    "reference": "PAY_20260110_ABC123",
    "status": "pending",
    "amount": 5000,
    "currency": "XOF",
    "payment_url": "https://...",  // Pour la carte (3DS)
    "ussd_code": "#144*82*...#"     // Pour Orange Money
  }
}

Paiement Orange Money

Requête

curl -X POST https://devs.mypaie.tech/api/v1/payments/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_test_xxx" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "orange_money",
    "phone": "+22370123456",
    "description": "Achat produit"
  }'

Format téléphone : Le numéro doit inclure l'indicatif pays (+223 pour le Mali)

Paiement par Carte Bancaire

curl -X POST https://devs.mypaie.tech/api/v1/payments/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_test_xxx" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "payment_method": "card",
    "customer_email": "client@email.com",
    "customer_name": "Amadou Diallo",
    "description": "Abonnement Premium"
  }'

GET /payments/{reference}

Vérifier le statut d'un paiement

curl https://devs.mypaie.tech/api/v1/payments/PAY_20260110_ABC123 \
  -H "X-API-Key: pk_test_xxx"

Statuts possibles

pending

processing

completed

failed

cancelled

refunded

Abonnements / Paiements Récurrents

Créez des plans d'abonnement et facturez automatiquement vos clients de manière récurrente.

Paiements Récurrents

Idéal pour les SaaS, abonnements, adhésions et services avec facturation périodique.

Flexible

Quotidien, hebdo, mensuel, annuel

Période d'essai

Offrez X jours gratuits

Pause/Reprise

Contrôle total des abonnements

Plans d'abonnement

Créez vos plans depuis le dashboard ou via l'API.

Exemple de plan

{
  "id": "plan_abc123",
  "name": "Premium",
  "description": "Accès complet à toutes les fonctionnalités",
  "amount": 9900,
  "currency": "XOF",
  "interval_type": "monthly",
  "interval_count": 1,
  "trial_days": 14,
  "status": "active"
}

Intervalles supportés

daily

Quotidien

weekly

Hebdomadaire

monthly

Mensuel

yearly

Annuel

Créer un abonnement

POST /api/v1/subscriptions

Souscrivez un client à un plan d'abonnement.

Requête

curl -X POST https://devs.mypaie.tech/api/v1/subscriptions \
  -H "X-API-Key: pk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_abc123",
    "customer_id": "cust_456",
    "customer_email": "client@example.com",
    "customer_phone": "+22370000000",
    "customer_name": "Amadou Diallo",
    "payment_method": "orange_money",
    "metadata": {
      "user_id": "12345"
    }
  }'

Réponse (Avec période d'essai)

{
  "success": true,
  "message": "Abonnement créé",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "trialing",
    "trial_ends_at": "2024-01-24T00:00:00Z",
    "current_period_end": "2024-01-24T00:00:00Z",
    "plan": {
      "id": "plan_abc123",
      "name": "Premium",
      "amount": 9900,
      "currency": "XOF",
      "interval": "monthly"
    }
  }
}

Réponse (Sans période d'essai - Paiement immédiat requis)

{
  "success": true,
  "message": "Abonnement créé, en attente de paiement initial",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "pending_payment",
    "trial_ends_at": null,
    "current_period_end": "2024-02-10T01:30:00Z",
    "plan": {
      "id": "plan_abc123",
      "name": "Premium",
      "amount": 9900,
      "currency": "XOF",
      "interval": "monthly"
    },
    "pay_url": "https://devs.mypaie.tech/invoice/pay/INV-202605-E2F8B1",
    "invoice_number": "INV-202605-E2F8B1"
  }
}

Paramètres

plan_id

requis

ID du plan d'abonnement

customer_id

optionnel

Identifiant unique du client dans votre système

customer_email

optionnel

Email du client

customer_phone

optionnel

Téléphone du client (format international)

payment_method

requis

orange_money ou card

Note: Au moins un identifiant client (customer_id, customer_email ou customer_phone) est requis.

Gérer les abonnements

GET /api/v1/subscriptions

Liste tous les abonnements de votre application.

Filtres: ?status=active ?customer_id=cust_123

GET /api/v1/subscriptions/{id}

Récupère les détails d'un abonnement avec son historique de factures.

POST /api/v1/subscriptions/{id}/cancel

Annule un abonnement.

{
  "immediate": false,
  "reason": "Client demande annulation"
}

immediate: true = annulation immédiate, false = à la fin de la période

POST /api/v1/subscriptions/{id}/pause

Met l'abonnement en pause (arrête la facturation).

POST /api/v1/subscriptions/{id}/resume

Reprend un abonnement en pause.

Statuts d'abonnement

trialing

active

paused

past_due

canceled

expired

pending_payment

Webhooks

Recevez des notifications en temps réel sur les événements de paiement.

Événements

payment.success Paiement réussi

payment.failed Paiement échoué

payment.expired Paiement expiré (timeout 1h sans confirmation)

payout.completed Reversement effectué

subscription.created Nouvel abonnement créé

subscription.payment_due Cycle d'abonnement à facturer (cron horaire)

subscription.canceled Abonnement annulé

Headers envoyés

X-MyPaie-Signature	HMAC-SHA256 du payload
X-MyPaie-Timestamp	Timestamp Unix de l'envoi
X-MyPaie-Event	Type d'événement

Vérifier la signature

PHP

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_MYPAIE_SIGNATURE'];
$secret = 'votre_webhook_secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    $event = json_decode($payload, true);
    // Traiter l'événement...
    http_response_code(200);
} else {
    http_response_code(401);
}

Split Payment

Ventilez automatiquement et instantanément le montant net d'une transaction entre vous (le marchand principal) et une plateforme tierce cliente.

Infrastructure Marketplace

Parfait pour les plateformes de livraison, applications de VTC (ex: reversement chauffeur/livreur) ou places de marché multi-vendeurs.

Fonctionnement

Dès qu'une transaction est initiée, si une règle de partage active est rattachée à l'application, MyPaie calcule et stocke la ventilation des fonds :

Commission MyPaie : Prélevée en premier selon votre taux standard (ex: 2.5%).
Part Marchand (Merchant Share) : Transférée vers votre solde de développeur.
Part Plateforme (Platform Share) : Réservée pour reversement vers le partenaire ou tiers.

Payload de transaction avec split

Exemple d'objet Transaction

{
  "reference": "PAY_20260617_A8B9C0",
  "amount": 10000,
  "currency": "XOF",
  "mypaie_fee": 250,
  "net_amount": 9750,
  "payment_method": "orange_money",
  "status": "completed",
  "split_rule_id": 4,
  "merchant_share": 7800,
  "platform_share": 1950
}

Tontines Numériques Automatisées

Gérez et automatisez des tontines numériques (Fintech Sociale/Épargne collaborative) avec cycle de collecte de cotisations et prélèvement automatique Mobile Money.

Le flux d'automatisation

1

Tirage au sort : Les positions de passage des membres sont attribuées aléatoirement pour structurer l'ordre des bénéficiaires.

2

Démon de collecte (USSD Push) : Le démon cron cron/process_tontines.php s'exécute périodiquement. Pour chaque membre n'ayant pas cotisé au cycle actif, il initie une transaction Mobile Money qui envoie un USSD Push de confirmation sur son mobile.

3

Double notification : En parallèle, le membre reçoit un Email et un SMS contenant son lien direct de checkout pour régler par Carte Bancaire en cas d'échec du Mobile Money.

4

Reversement (Payout) : Dès que 100% des cotisations du cycle sont validées (statut ready_payout), la cagnotte globale est prête à être versée au bénéficiaire désigné.

Protection Acheteur & B2C

Inspiré du modèle historique de PayPal, MyPaie intègre un système de confiance bilatéral avec un espace pour les acheteurs particuliers (B2C) et un mécanisme de séquestre (escrow) automatique de 72h.

Le Séquestre Automatique (72 heures)

Pour toutes les transactions de paiement en ligne, les fonds sont placés sous séquestre au statut held pendant un délai de **72 heures ouvrées**.

Libération automatique : Après 72 heures sans incident, les fonds sont libérés vers le solde disponible du marchand.
Opposition / Litige : Si le client déclare n'avoir pas reçu sa commande, les fonds restent bloqués en séquestre le temps de l'arbitrage.

Dépôt de Litige (Faire opposition)

L'acheteur peut déposer une réclamation directement en ligne sur la page dédiée :

GET https://devs.mypaie.tech/disputes/file?reference=PAY-xxxxxxxxxxxx

Le marchand dispose de 72h ouvrées pour répondre et apporter une preuve de livraison. Sans réponse ou si la réclamation est approuvée, l'acheteur est intégralement remboursé.

Compte Particulier & Checkout 1-Click

Les particuliers peuvent créer un compte pour lier et tokeniser leurs moyens de paiement (cartes bancaires, comptes Orange Money, Wave...) afin d'effectuer des achats en **1-Click** sur tous les checkouts partenaires.

Espace Particulier

Accessible sur /consumer/login pour gérer ses moyens liés, payer ses assurances auto/voyage et suivre ses litiges.

Checkout 1-Click

Intégré nativement dans le checkout MyPaie pour un paiement ultra-rapide par OTP SMS sans saisie des coordonnées.

Codes d'erreur

Code	Description
`VALIDATION_ERROR`	Paramètres de requête invalides
`UNAUTHORIZED`	Clé API invalide ou manquante
`NOT_FOUND`	Ressource non trouvée
`PROVIDER_ERROR`	Erreur du fournisseur de paiement
`RATE_LIMITED`	Limite de requêtes atteinte (100/min)

SDKs

PHP

composer require mypaie/sdk

Documentation → Télécharger

Node.js

npm install mypaie-node

Documentation → Télécharger

JavaScript (Browser)

<script src="mypaie.js">

Documentation → Télécharger

Flutter / Dart

mypaie_flutter: ^1.0.0

Documentation → Télécharger

JavaScript (Browser) - Exemple rapide

<!-- Inclure le SDK -->
<script src="https://devs.mypaie.tech/sdk/javascript/mypaie.js"></script>

<!-- Bouton de paiement -->
<div id="pay-button"></div>

<script>
new MyPaieButton('#pay-button', {
    apiKey: 'pk_test_xxx',
    amount: 5000,
    currency: 'XOF',
    description: 'Commande #123',
    buttonText: 'Payer 5 000 XOF',
    successUrl: 'https://monsite.com/success'
});
</script>

Tester l'API

Testez l'API en direct avec notre page de démonstration.

Ouvrir la démo

Documentation API MyPaie

Orange Money

Carte Bancaire

URL de base

Authentification

Démarrage rapide

Créez une session de paiement

Redirigez le client

Recevez la notification

Créer une session de checkout

Paramètres

Exemple de requête

Réponse

Initier un paiement direct

Paramètres communs

Réponse

Paiement Orange Money

Paiement par Carte Bancaire

Vérifier le statut d'un paiement

Statuts possibles

Abonnements / Paiements Récurrents

Paiements Récurrents

Plans d'abonnement

Intervalles supportés

Créer un abonnement

Paramètres

Gérer les abonnements

Statuts d'abonnement

Webhooks

Événements

Headers envoyés

Vérifier la signature

Split Payment

Infrastructure Marketplace

Fonctionnement

Payload de transaction avec split

Tontines Numériques Automatisées

Le flux d'automatisation

Protection Acheteur & B2C

Le Séquestre Automatique (72 heures)

Dépôt de Litige (Faire opposition)

Compte Particulier & Checkout 1-Click

Codes d'erreur

SDKs

PHP

Node.js

JavaScript (Browser)

Flutter / Dart

Tester l'API

Assistant IA MyPaie