Si tu construis une application de paiement en Afrique du Sud, tu vas croiser le nom Stitch rapidement. Certifiée ISO 27001 et PCI DSS Level 1, utilisée par Takealot, MTN SA, Vodacom, Betway et FlySafair, Stitch est aujourd’hui la passerelle de paiement enterprise de référence sur le marché sud-africain. Ce qui la distingue techniquement des autres solutions du continent : une API entièrement en GraphQL (pas REST), une couverture complète des méthodes de paiement locales incluant Pay By Bank, Capitec Pay, DebiCheck et Apple/Google Pay. Elle offre des outils de développement sérieux avec un IDE GraphQL interactif en ligne et un sandbox complet. Ce guide couvre tout ce qu’un développeur doit savoir pour intégrer Stitch en 2026 : architecture, code samples copiables, tarifs réels et comparatif avec les alternatives.
Stitch en 2026 : ce que la plateforme couvre vraiment
La plateforme en chiffres
Stitch est une fintech fondée à Cape Town, opérant exclusivement en Afrique du Sud. Elle se positionne explicitement comme une passerelle enterprise. Ses clients visibles sur le site parlent d’eux-mêmes : Takealot (le plus grand e-commerçant d’Afrique du Sud),
- MTN SA ;
- Vodacom ;
- Betway ;
- Bash ;
- Mr D (Delivery Hero SA) ;
- FlySafair,
- Luno ;
- The Courier Guy.
Ce ne sont pas des startups qui testent une API ; ce sont des entreprises qui traitent des millions de transactions par mois.
La certification ISO 27001 couvre la sécurité des systèmes d’information. La certification PCI DSS Level 1 est le niveau le plus élevé de conformité pour le traitement des données de carte bancaire. Le niveau auquel sont soumis les processeurs qui traitent plus de 6 millions de transactions carte par an.
Les produits disponibles
Stitch propose un catalogue complet de méthodes de paiement, toutes accessibles via la même API GraphQL :
- Paiements entrants (Payins) :
- Pay By Bank : virement bancaire direct, sans réseau carte, plus rapide et moins cher qu’une transaction carte classique ;
- Capitec Pay : intégration native avec Capitec Bank, la banque la plus utilisée d’Afrique du Sud par nombre de clients actifs ;
- Card : débit et crédit, paiements ponctuels ou récurrents avec tokenisation ;
- DebiCheck : prélèvement automatique récurrent avec mandat électronique, le standard sud-africain pour les collections ;
- Manual EFT : virement manuel initié depuis l’application bancaire de l’utilisateur ;
- Cash : paiements en espèces via ATM, crédités automatiquement sur le compte digital du client ;
- Pay with Crypto : accepter des paiements en cryptomonnaie sans gérer la conversion vers le rand ;
- Wallets : Apple Pay, Samsung Pay, Google Pay pour les paiements mobiles.
- Paiements sortants (Payouts) :
- Décaissements 24h/24, 7j/7, 365 jours par an : remboursements, retraits, versements aux fournisseurs ou aux livreurs.
- Paiements en personne (In-person) :
- API pour terminaux POS avec gestion des paiements carte présente et méthodes alternatives au point de vente.
- Open finance et data :
- Bank Account Verification (BAV) : vérifier qu’un compte bancaire appartient bien à l’utilisateur avant d’initier un paiement ;
- Vault : tokenisation sécurisée des données de paiement ;
- Bank Queries : accès aux données bancaires de l’utilisateur avec son consentement
Architecture de l’API : pourquoi GraphQL plutôt que REST ?
C’est le premier point qui surprend les développeurs habitués aux APIs REST africaines (Paystack, Flutterwave, Stripe Africa). Stitch a fait le choix délibéré de GraphQL pour l’intégralité de son API, et ce choix est documenté et assumé dans leur blog technique.
Les trois avantages concrets pour un dev
Typage fort : Le schéma GraphQL de Stitch est strictement typé. Quand tu intègres un Payment Request, les types `PaymentInitiationRequestCompleted`, `PaymentInitiationRequestCancelled`, `PaymentInitiationRequestExpired` et `PaymentInitiationRequestPending` sont définis dans le schéma. Ton IDE te prévient si tu manques un état. Avec REST, tu découvres les cas non gérés en production.
Queries ciblées : Tu demandes exactement les champs dont tu as besoin. Si tu veux juste l’`id` et le `url` d’un Payment Request, tu ne reçois que ça ; pas un objet de 40 champs dont tu utilises deux. Résultat, tu as moins de données sur le réseau, moins de parsing côté client, et des requêtes plus rapides.
Données interconnectées : Une seule query peut récupérer un paiement, son état, les informations du payeur et l’historique des événements en un seul appel réseau. Avec REST, ça aurait nécessité trois endpoints différents.
Authentification : deux types de tokens
L’API Stitch utilise OAuth2. Il existe deux types de tokens selon l’opération :
- Client token : pour les Payment Requests et les opérations côté marchand (créer un paiement, vérifier son statut, initier un payout). S’obtient via `client\_credentials` grant.
- User token : pour accéder aux données bancaires d’un utilisateur (Bank Queries, BAV). Nécessite le consentement explicite de l’utilisateur via un flow OAuth2 complet.
Exemple : vérifier le statut d’un Payment Request
« `graphql
# Query : récupérer le statut d’un Payment Request par son ID
query GetPaymentRequestStatus($paymentRequestId: ID!) {
node(id: $paymentRequestId) {
… on PaymentInitiationRequest {
id
url
payerReference
state {
\_\_typename
… on PaymentInitiationRequestCompleted {
date
amount
payer {
… on PaymentInitiationBankAccountPayer {
accountNumber
bankId
}
}
}
… on PaymentInitiationRequestPending {
\_\_typename
}
… on PaymentInitiationRequestCancelled {
date
reason
}
… on PaymentInitiationRequestExpired {
\_\_typename
date
}
}
}
}
}
« `
Variables :
« `json
{
« paymentRequestId »: « cGF5cmVxL2Q5M2ZhODRlLTQ0YTgtNGY5MC1hODMyLTNmMmI1NWUyZDkyZg== »
}
« `
Ce pattern `… on TypeName` est la syntaxe GraphQL pour le polymorphisme — tu gères chaque état possible explicitement, sans risquer d’ignorer un cas.
Tuto : créer un paiement Pay By Bank de bout en bout en 5 étapes
Pay By Bank est le produit phare de Stitch pour le marché sud-africain. Il permet à un client de payer directement depuis son application bancaire, sans carte, sans intermédiaire comme Visa ou Mastercard. Le flux est plus rapide, le règlement plus immédiat, et la commission pour le marchand est inférieure à celle d’une transaction carte.
Étape 1 : Obtenir un client token
« `bash
curl –request POST \\
–url https://secure.stitch.money/connect/token \\
–header ‘Content-Type: application/x-www-form-urlencoded’ \\
–data ‘grant\_type=client\_credentials’ \\
–data ‘client\_id=TON\_CLIENT\_ID’ \\
–data ‘client\_secret=TON\_CLIENT\_SECRET’ \\
–data ‘audience=https://secure.stitch.money/connect/token’ \\
–data ‘scope=client\_paymentrequest’
« `
La réponse contient un `access\_token` JWT à passer dans le header `Authorization: Bearer <token>` de toutes tes requêtes GraphQL.
Étape 2 : Créer le Payment Request via mutation GraphQL
« `graphql
mutation CreatePaymentRequest($input: PaymentInitiationRequestInput!) {
clientPaymentInitiationRequestCreate(input: $input) {
paymentInitiationRequest {
id
url
}
}
}
« `
Variables correspondantes :
« `json
{
« input »: {
« amount »: {
« quantity »: « 500.00 »,
« currency »: « ZAR »
},
« payerReference »: « Order-1234 »,
« beneficiaryReference »: « MaBoutique »,
« merchant »: « TON\_MERCHANT\_ID »,
« beneficiary »: {
« bankAccount »: {
« name »: « Ma Boutique SARL »,
« bankId »: « fnb »,
« accountNumber »: « 62425239471 »,
« accountType »: « current »,
« beneficiaryType »: « business »,
« reference »: « Order-1234 »
}
}
}
}
« `
La mutation retourne un `id` (pour les webhooks et les vérifications de statut) et une `url` vers laquelle rediriger l’utilisateur.
Étape 3 : Rediriger l’utilisateur
Redirige l’utilisateur vers l’`url` retournée. Stitch prend en charge le choix de la banque, l’authentification et la confirmation du virement. Tu n’as rien à implémenter côté frontend pour cette étape.
Étape 4 : Écouter le webhook de confirmation
Configure ton endpoint webhook dans le dashboard Stitch. Stitch envoie un événement POST à ton URL dès que le statut du paiement change.
Étape 5 : Vérifier le statut en fallback
Si le webhook n’arrive pas (réseau, timeout), interroge l’API avec la query `GetPaymentRequestStatus` vue plus haut pour récupérer l’état courant.
Tarifs Stitch : ce qui est public et comment ça se négocie
Stitch ne publie pas de grille tarifaire publique. C’est le modèle standard des passerelles enterprise qui vendent sur devis après qualification du client. Leur site redirige vers « Contact Sales » pour tout ce qui concerne les tarifs. Ce que l’on sait est établi à partir des pratiques documentées du marché sud-africain.
Le modèle est une commission par transaction sans abonnement mensuel connu. Pay By Bank revient généralement moins cher que la carte pour le marchand. L’absence du réseau Visa/Mastercard élimine une couche de frais d’interchange. Les transactions carte en Afrique du Sud se situent typiquement entre 1,5 et 2,5% selon le volume négocié. Les payouts sont facturés à un tarif fixe ou en pourcentage selon les volumes.
Tableau comparatif : Stitch vs Paystack vs Flutterwave en Afrique du Sud
| Critère | Stitch | Paystack | Flutterwave |
| Couverture géographique | Afrique du Sud uniquement | Nigeria + ZA + autres | 30+ pays dont ZA |
| Pay By Bank natif | ✅ Produit phare | ❌ | ❌ |
| Capitec Pay | ✅ Intégré | ❌ | ❌ |
| Tarif carte déclaré | Non public, sur devis | ~1,5% (Nigeria) | ~1,4%+ selon pays |
| Architecture API | GraphQL | REST | REST |
| PCI DSS Level 1 | ✅ | ✅ | ✅ |
| Mobile Money MTN/Moov | ❌ | ❌ en ZA | ✅ autres pays |
| DebiCheck (collections) | ✅ | ❌ | ❌ |
| Sandbox gratuit | ✅ | ✅ | ✅ |
| IDE interactif en ligne | ✅ (GraphQL IDE) | ❌ | ❌ |
| Cible principale | Enterprise ZA | PME Nigeria/ZA | PME panafricaine |
La lecture de ce tableau montre clairement que Stitch n’est pas le bon choix si tu veux couvrir plusieurs pays africains ou intégrer du Mobile Money MTN ou Orange en dehors de l’Afrique du Sud. C’est le meilleur choix si tu construis un produit sérieux exclusivement pour le marché sud-africain et que tu veux accéder à Pay By Bank, Capitec Pay et DebiCheck avec une API bien documentée et une certification enterprise.
Webhooks, états de paiement et gestion des erreurs
Cette section est la plus critique pour passer d’une intégration qui « marche en sandbox » à une intégration production-ready.
Les 4 états possibles d’un Payment Request
Tout Payment Request Stitch traverse un cycle de vie défini par 4 états exclusifs. Les gérer tous les quatre n’est pas optionnel :
- `PaymentInitiationRequestPending` : le Payment Request a été créé, l’utilisateur ne l’a pas encore complété ;
- `PaymentInitiationRequestCompleted` : le paiement a été reçu et confirmé ;
- `PaymentInitiationRequestCancelled` : l’utilisateur a annulé le paiement (champ `reason` disponible) ;
- `PaymentInitiationRequestExpired` : le délai a expiré sans action de l’utilisateur.
Implémenter un endpoint webhook en Node.js / Express
« `javascript
const express = require(‘express’);
const app = express();
app.use(express.json());
app.post(‘/webhook/stitch’, (req, res) => {
const event = req.body;
// Toujours répondre 200 rapidement pour éviter les retries Stitch
res.status(200).send(‘OK’);
// Traiter l’événement de façon asynchrone
handleStitchEvent(event);
});
async function handleStitchEvent(event) {
switch (event.\_\_typename) {
case ‘PaymentInitiationRequestCompleted’:
const { amount, date, payer } = event;
console.log(`Paiement reçu : ${amount.quantity} ${amount.currency}`);
// await updateOrder(event.payerReference, ‘paid’);
// await sendConfirmationEmail(event.payerReference);
break;
case ‘PaymentInitiationRequestCancelled’:
console.log(`Paiement annulé – Raison : ${event.reason}`);
// await updateOrder(event.payerReference, ‘cancelled’);
break;
case ‘PaymentInitiationRequestExpired’:
console.log(`Paiement expiré le ${event.date}`);
// await updateOrder(event.payerReference, ‘expired’);
// Optionnel : notifier l’utilisateur pour relancer le paiement
break;
case ‘PaymentInitiationRequestPending’:
// Pas d’action requise — état intermédiaire
break;
default:
console.warn(`Événement Stitch inconnu : ${event.\_\_typename}`);
}
}
app.listen(3000, () => console.log(‘Webhook Stitch en écoute sur le port 3000’));
« `
Pagination des Payment Requests
Pour récupérer l’historique de tes paiements avec pagination, Stitch suit la spec Relay — un standard GraphQL pour la pagination basé sur des curseurs :
« `graphql
query ListPaymentRequests($pageCursor: Cursor) {
client {
paymentInitiationRequests(first: 50, after: $pageCursor) {
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
amount
payerReference
created
state {
\_\_typename
… on PaymentInitiationRequestCompleted {
date
amount
}
}
}
}
}
}
}
« `
Pour paginer, passe `endCursor` de `pageInfo` en tant que `pageCursor` sur la prochaine requête. Les résultats sont en ordre chronologique inverse. Le `after` pagine donc vers le passé.
Stitch Express : pour les e-commerçants sans ressources dev
Tous les marchands n’ont pas une équipe technique capable d’intégrer une API GraphQL. Stitch a prévu le cas avec Stitch Express. Une offre de plugins et d’applications pour les plateformes e-commerce les plus utilisées en Afrique du Sud.
Stitch Express est disponible pour Shopify, WooCommerce, Squarespace et Webflow. L’intégration est sans code : tu installes le plugin, tu connectes ton compte Stitch, et tu accèdes à toutes les méthodes de paiement Stitch dans ton checkout (Pay By Bank, carte, Apple Pay, Google Pay) sans écrire une ligne de code.
Le produit est décrit par Stitch comme « construit sur une technologie de paiement enterprise, pensé pour une expérience de checkout de classe mondiale« . En pratique, ça signifie que les petits marchands e-com bénéficient de la même infrastructure technique que Takealot, avec une intégration plug-and-play.
FAQ développeur
Stitch fonctionne-t-il hors Afrique du Sud ?
Non, pas dans l’état actuel de l’offre. Stitch est une passerelle exclusivement sud-africaine. Toutes ses méthodes de paiement (Pay By Bank, Capitec Pay, DebiCheck, EFT) sont spécifiques au marché et au système bancaire sud-africain. Si tu dois couvrir le Nigeria, le Kenya, le Ghana ou des pays UEMOA, tu as besoin d’une autre solution : Flutterwave et Paystack pour l’Anglophone, FedaPay, CinetPay ou Hub2 pour le Francophone.
Peut-on tester l’intégration sans compte de production ?
Oui. Stitch propose un sandbox complet documenté sur docs.stitch.money, avec des données de test et un IDE GraphQL interactif disponible sur ide.stitch.money qui permet de tester des queries directement dans le navigateur. C’est l’un des meilleurs environnements de test du secteur. Tu peux valider ton intégration complète, y compris les webhooks, sans créer de compte production.
Stitch supporte-t-il les paiements récurrents et les subscriptions ?
Oui, via deux produits distincts. DebiCheck est le standard sud-africain pour les prélèvements automatiques récurrents. Il inclut un système de mandat électronique (l’utilisateur autorise les prélèvements futurs via son application bancaire). Card avec tokenisation permet de stocker les données de carte de façon sécurisée pour des charges récurrentes sans redemander les informations de carte à chaque transaction. Les deux sont accessibles via la même API GraphQL.
Comment gérer un webhook qui n’arrive pas ?
La bonne pratique est de toujours implémenter une double vérification. Le webhook pour les confirmations en temps réel, et un polling de fallback via la query `GetPaymentRequestStatus` pour les cas où le webhook échoue (timeout réseau, restart de serveur, déploiement). Stitch recommande également de répondre `200 OK` immédiatement à chaque webhook reçu avant de traiter l’événement. Si ton endpoint met trop de temps à répondre, Stitch peut considérer la livraison comme échouée et retenter.
Conclusion
Stitch est la passerelle technique la plus solide du marché sud-africain pour les équipes qui construisent des produits de paiement sérieux. Son API GraphQL bien documentée, son sandbox interactif, sa certification PCI DSS Level 1 et sa couverture native de Pay By Bank et DebiCheck en font le choix logique pour tout projet qui cible l’Afrique du Sud en priorité.
Ses limites sont tout aussi claires. Elle ne couvre qu’un seul pays, ne propose pas de Mobile Money panafricain et s’adresse à des équipes qui ont les ressources pour intégrer une API GraphQL. Pour les marchands sans équipe dev, Stitch Express résout ce problème sur les plateformes e-commerce standards.
Si tu construis pour l’Afrique du Sud, commence par le sandbox. L’IDE interactif sur ide.stitch.money te permet de tester ta première query en moins de cinq minutes. La documentation sur docs.stitch.money est complète, en anglais, et régulièrement maintenue. Tu intègres Stitch sur un projet spécifique et tu as une question technique ? Laisse-la en commentaire sur NextUltra Tech. Les devs de la communauté partagent leurs retours d’expérience.