MASSPAY · v1.0

Paiements en masse

Versez salaires, bourses ou commissions vers des centaines de bénéficiaires en une seule requête. Traitement asynchrone avec suivi individuel par bénéficiaire.

Introduction

MassPay vous permet d'envoyer de l'argent à plusieurs destinataires en même temps, depuis votre compte marchand BluePay. Idéal pour les bourses étudiantes, salaires, remboursements et primes.

📦
Un seul appel API
Envoyez jusqu'à 100 paiements en une seule requête POST.
📡
Traitement asynchrone
BluePay traite le batch en arrière-plan. Suivez chaque paiement via webhook.
🔀
Multi-opérateurs
Wave, Orange Money, Free Money dans un même batch.

Créer un batch

POST/api/v1/mass-pay
ChampTypeRequisDescription
labelstringOuiNom du batch (ex : "Bourses S1 2026")
recipientsarrayOuiTableau de bénéficiaires (max 100)
→ phonestringOuiTéléphone du bénéficiaire au format international
→ amountintegerOuiMontant à verser en centimes XOF
→ channelstringOuiWAVE | ORANGE_MONEY | FREE_MONEY
→ referencestringNonRéférence interne pour ce bénéficiaire
→ metadataobjectNonDonnées libres retournées dans le webhook
JavaScript
const res = await fetch('https://bluepay.myfad.org/api/v1/mass-pay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer bluepay_live_votre_cle',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    label: 'Bourses étudiantes S1 2026',
    recipients: [
      {
        phone: '+221771234567',
        amount: 75000,           // 750 XOF
        channel: 'WAVE',
        reference: 'UCK-2026-001',
        metadata: { studentId: 'UCK-2026-001', filiere: 'L3-INFO' },
      },
      {
        phone: '+221785550033',
        amount: 75000,
        channel: 'ORANGE_MONEY',
        reference: 'UCK-2026-002',
        metadata: { studentId: 'UCK-2026-002', filiere: 'L3-MATHS' },
      },
      // ... jusqu'à 100 bénéficiaires
    ],
  }),
});

const { batchId, status } = await res.json();
console.log('Batch créé :', batchId, '— statut :', status);
// Batch créé : batch_c7f2a... — statut : QUEUED
JSON (réponse)
{
  "batchId": "batch_c7f2a8b3d4e5f6a7",
  "label": "Bourses étudiantes S1 2026",
  "status": "QUEUED",
  "totalRecipients": 2,
  "totalAmount": 150000,
  "currency": "XOF",
  "createdAt": "2026-06-30T10:00:00.000Z"
}
⚠
Le batch est traité de façon asynchrone. Ne supposez pas que les paiements ont eu lieu dès la réponse 200. Attendez les webhooks individuels ou interrogez le statut.

Suivi du batch

GET/api/v1/mass-pay/:batchId
JSON (réponse en cours)
{
  "batchId": "batch_c7f2a8b3d4e5f6a7",
  "label": "Bourses étudiantes S1 2026",
  "status": "PROCESSING",
  "progress": {
    "total": 2,
    "success": 1,
    "failed": 0,
    "pending": 1
  },
  "recipients": [
    {
      "reference": "UCK-2026-001",
      "phone": "+221771234567",
      "amount": 75000,
      "channel": "WAVE",
      "status": "SUCCESS",
      "processedAt": "2026-06-30T10:00:05.000Z"
    },
    {
      "reference": "UCK-2026-002",
      "phone": "+221785550033",
      "amount": 75000,
      "channel": "ORANGE_MONEY",
      "status": "PENDING",
      "processedAt": null
    }
  ]
}
QUEUEDEn file d'attente
PROCESSINGEn traitement
COMPLETEDTous traités
PARTIALPartiellement réussi
FAILEDTous échoués
CANCELLEDAnnulé avant traitement

Webhooks MassPay

BluePay envoie un webhook pour chaque bénéficiaire dès que son paiement est traité, et un webhook final quand le batch est terminé.

JSON (paiement individuel)
{
  "event": "masspay.recipient.success",
  "data": {
    "batchId": "batch_c7f2a8b3d4e5f6a7",
    "reference": "UCK-2026-001",
    "phone": "+221771234567",
    "amount": 75000,
    "channel": "WAVE",
    "status": "SUCCESS",
    "metadata": { "studentId": "UCK-2026-001", "filiere": "L3-INFO" }
  }
}
JSON (batch terminé)
{
  "event": "masspay.batch.completed",
  "data": {
    "batchId": "batch_c7f2a8b3d4e5f6a7",
    "label": "Bourses étudiantes S1 2026",
    "status": "COMPLETED",
    "progress": { "total": 2, "success": 2, "failed": 0 }
  }
}

Exemple — Versement des bourses UCAD

Python (script de versement)
import requests, csv

API_KEY  = 'bluepay_live_votre_cle'
BASE_URL = 'https://bluepay.myfad.org'

# Charger la liste des boursiers depuis un CSV
# Colonnes : nom, telephone, montant, operateur, matricule
recipients = []
with open('boursiers_s1_2026.csv') as f:
    for row in csv.DictReader(f):
        recipients.append({
            'phone':     row['telephone'],
            'amount':    int(row['montant']),
            'channel':   row['operateur'].upper(),
            'reference': row['matricule'],
            'metadata':  {'nom': row['nom'], 'matricule': row['matricule']},
        })

# Découper en lots de 100
def chunks(lst, n):
    for i in range(0, len(lst), n):
        yield lst[i:i + n]

for i, batch in enumerate(chunks(recipients, 100), 1):
    res = requests.post(
        f'{BASE_URL}/api/v1/mass-pay',
        headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'},
        json={
            'label': f'Bourses S1 2026 — Lot {i}',
            'recipients': batch,
        }
    )
    data = res.json()
    print(f'Lot {i} créé — batchId: {data["batchId"]} | {len(batch)} bénéficiaires | {data["totalAmount"]} XOF')

Commencer avec MassPay

Gérez vos versements en masse depuis le dashboard ou directement via l'API.

Dashboard →Swagger MassPay →