Développeurs
Une API. Tous les réseaux.
Intégrez les paiements congolais sans gérer quatre intégrations, quatre formats de réponse et quatre supports. AlmaPay expose un seul contrat technique, documenté et testable.
Principes
Ce que nous avons simplifié pour vous.
Un statut, pas quatre
Chaque paiement possède un identifiant AlmaPay et un statut unique : en attente, réussi, échoué, remboursé. Fini les réponses opérateur contradictoires.
Des webhooks signés
Chaque notification est signée. Vérifiez la signature, traitez l'événement, répondez 200. Les rejeux sont sûrs grâce à l'idempotence.
Un mode test
Développez et validez vos parcours sans mouvement d'argent réel. Les clés de test et de production sont séparées.
Exemple
Créer un paiement en une requête.
Le montant est exprimé en francs congolais, en nombre entier. La référence est la vôtre : elle sera renvoyée dans chaque webhook et dans le relevé de règlement.
- Une clé API par environnement
- Montants en entiers, jamais en flottants
- Référence marchande unique et obligatoire
import Alma from "@almapay/node";
const alma = new Alma(process.env.ALMA_SECRET_KEY);
app.post("/checkout", async (req, res) => {
const payment = await alma.payments.create({
amount: 125000,
currency: "CDF",
operator: "mpesa",
reference: "CMD-A1042",
customer: { phone: req.body.phone },
return_url: "https://exemple.cd/merci"
});
res.json({ checkout_url: payment.checkout_url });
});
// Webhook : vérifier la signature avant tout traitement
app.post("/webhooks/alma", alma.webhooks.verify(), (req, res) => {
if (req.event.type === "payment.succeeded") {
fulfillOrder(req.event.data.reference);
}
res.sendStatus(200);
});Endpoints
Les ressources principales.
Les chemins ci-dessous sont indicatifs et confirmés dans la documentation remise à l'intégration. Les évolutions sont versionnées.
| Méthode | Endpoint | Usage |
|---|---|---|
| POST | /v1/payments/create | Créer un paiement et obtenir l'URL de confirmation |
| GET | /v1/payments/verify | Vérifier le statut d'un paiement |
| POST | /v1/payments/refund | Rembourser tout ou partie d'un paiement |
| GET | /v1/collections | Lister les encaissements |
| POST | /v1/disbursements | Créer un décaissement ou un lot |
| GET | /v1/settlements | Consulter les règlements |
| GET | /v1/balance | Lire le solde du compte marchand |
Sécurité
Les bons réflexes, dès le premier jour.
Un paiement mobile se confirme côté serveur, jamais côté navigateur. AlmaPay fournit les briques, votre intégration doit appliquer les règles.
- Vérifier la signature de chaque webhook
- Ne jamais faire confiance au retour client seul
- Stocker la référence et l'identifiant AlmaPay
- Rendre le traitement idempotent
- Journaliser les événements et les rejeux
Intégration
Un accompagnement humain.
Notre équipe technique est basée à Kinshasa. Elle vous aide à cadrer le flux, à tester les cas d'échec et à passer en production sans surprise.
1. Cadrage
Nous validons ensemble le parcours, les canaux et les règles de règlement.
2. Test
Vous intégrez avec les clés de test, nous vérifions les webhooks et les cas limites.
3. Production
Bascule progressive, surveillance des premières transactions et support prioritaire.
Prêt à intégrer les paiements congolais ?
Écrivez-nous avec votre stack, votre volume estimé et votre échéance. Nous vous envoyons la documentation et un accès de test.
Contacter l'équipe technique