Orchestration des paiements

Vous ne nommez jamais de prestataire dans un paiement. La requête ne contient aucun champ provider et vous ne pouvez pas en ajouter. Pour chaque paiement live, Wajub construit une liste ordonnée des connexions capables de le traiter. Il les essaie depuis le début et descend dans la liste lorsqu'une connexion échoue avant d'atteindre l'opérateur.

Cette liste représente la décision d'orchestration. Cette page explique ce qui la façonne : ce que vous contrôlez, ce que Wajub décide pour vous et ce que vous pouvez observer ensuite.

1. 1Vous ne choisissez aucun prestataire

   Un appel porte un montant et un canal. Wajub choisit.

2. 2Un refus n'est pas un débit

   Le payeur garde une seule référence sur toute la cascade.

3. 3Le premier oui met fin à la cascade

   Un prestataire accepte et plus rien n'est tenté.

Qui décide quoi

L'orchestration n'est pas une fonctionnalité à activer. C'est le seul chemin emprunté par un paiement live, et la répartition des responsabilités ne change jamais.

Aucune décision de ce tableau ne peut être exprimée au moment de l'appel. Si vous avez besoin d'un prestataire précis dans un cas donné, utilisez une règle de routage, une politique de canal ou une priorité, définie une seule fois dans le Dashboard, pas un paramètre envoyé avec la requête.

La route est décidée au deuxième appel

Un paiement nécessite deux appels. Seul le second effectue le routage.

Cette différence vient du canal. Le routage utilise toujours le canal de l'opérateur, et l'opérateur n'est souvent connu qu'une fois le numéro du payeur connu. Une requête pour cm.mobile avec le numéro +237 6 70 00 00 00 est routée comme cm.mtn. Une requête qui indique cm.mtn avec un numéro Orange est refusée avec une réponse 422 qui précise l'incompatibilité, au lieu d'être redirigée discrètement.

Les connexions qui peuvent prendre le paiement

Avant tout classement, Wajub ne garde que les connexions capables de traiter ce paiement précis. Une connexion n'est essayée que si toutes ces conditions sont remplies :

• la connexion est active, tout comme le prestataire : Disponible ou en Bêta, ni en maintenance, ni bientôt disponible, ni désactivé ;
• le prestataire peut traiter le canal du paiement, et la liste de canaux de votre connexion l'autorise ;
• la connexion accepte la devise du paiement ;
• Wajub peut débiter par ce prestataire (les prestataires pas encore pris en charge sont marqués Bientôt disponible) ;
• la connexion n'est pas en pause sur ce canal après des échecs répétés. Une connexion en pause apparaît comme ignorée dans le Routing Log.

Une restriction de pays agit un niveau au-dessus. Lorsqu'une restriction active sur votre compte couvre le pays du payeur, tout le paiement s'arrête avec 403 country_restricted, et non avec le 422 d'une liste vide (Erreurs de restriction).

Deux de ces conditions sont permissives lorsqu'elles sont vides, ce qui surprend souvent au début. Une connexion sans liste de canaux accepte tous les canaux pris en charge globalement par le prestataire. Une connexion sans liste de devises accepte toutes les devises. La restriction est un choix, pas le comportement par défaut.

L'instruction la plus précise passe en premier

Les connexions restantes sont ordonnées en deux temps. Vos règles placent d'abord leurs connexions. Toutes les autres sont ensuite ordonnées par la politique du canal lorsqu'il en a une active, ou par la priorité lorsqu'il n'en a pas. La liste se lit donc toujours de la même façon : ce que vos règles ont désigné, puis le reste.

Les règles passent en premier, quelle que soit la priorité

Une connexion désignée par une règle correspondante est essayée avant toutes les connexions qu'aucune règle ne désigne, quelle que soit la priority des unes et des autres. C'est le rôle d'une règle : vous l'avez écrite pour ce cas, elle l'emporte donc sur l'ordre général. Le prestataire de secours de la règle vient juste derrière sa cible. La page Règles de routage explique quelle règle l'emporte lorsque plusieurs correspondent.

Puis la politique du canal, s'il en a une

Une politique se définit par canal d'opérateur, dans Orchestration, Matrice, avec le bouton Politique de la ligne du canal. Lorsqu'elle est active, elle ordonne toutes les connexions qu'aucune règle n'a placées, et la priority de vos connexions ne départage plus que celles qu'elle laisse à égalité.

Une connexion sous votre santé minimale ou au-dessus de votre plafond de coût est essayée après les autres, y compris les connexions de votre ordre de cascade.

Puis la priorité, et le coût et la réussite récente à l'intérieur

Sur un canal sans politique active, les connexions sont regroupées selon l'entier priority de votre connexion. Le groupe le plus élevé est essayé entièrement avant de passer au suivant. La valeur par défaut est 0. Toutes les connexions d'un marchand qui n'a jamais défini de priorité se trouvent donc dans un même groupe.

À l'intérieur d'une même priorité, Wajub favorise la connexion la moins chère pour ce paiement, d'après les tarifs négociés que vous avez saisis sur vos connexions (pas la tarification propre à Wajub), et celle qui réussit le mieux récemment sur ce canal pour votre compte. Seuls les échecs du côté du prestataire ou de l'opérateur pèsent sur la réussite récente : le portefeuille vide d'un payeur n'y change rien.

Les connexions encore à égalité se partagent le trafic selon leur weight, dont la valeur par défaut est 100. Placez deux connexions à la même priorité, avec des poids de 70 et 30. Lorsque rien d'autre ne les distingue, environ sept paiements sur dix commenceront par la première. Une connexion de poids 0 n'est essayée qu'après celles dont le poids est non nul. Le poids répartit de la même façon le trafic entre les connexions qu'une politique de canal laisse à égalité.

Une décision complète

Prenons un paiement de 25 000 XAF sur cm.mtn, pour un compte doté de quatre connexions capables d'atteindre ce numéro et d'une règle qui associe le pays, le canal et la devise à CinetPay, sans politique sur le canal. Les quatre connexions aboutissent au même portefeuille MTN. Le classement décide laquelle le prend en charge.

Décision de routage · cm.mtn · 25 000 XAF

Quatre connexions atteignent le même portefeuille. Une était hors rotation, la cible de la règle est passée en premier et la deuxième a traité le paiement.

1. 1
   cinetpay

   délai opérateur dépassé8.0 s

   priority 50règle correspondanteréussite récente
2. 2
   flutterwave

   accepté0.9 s

   priority 100coût le plus basréussite récente
3. 3
   pawapay

   jamais appelée

   priority 50
4. notchpay

   Ignorée (circuit ouvert). La connexion a été mise en pause sur ce canal après des échecs répétés.

Lisez cette représentation depuis le bas. NotchPay ne figurait pas du tout dans le classement, car il était en pause sur ce canal. PawaPay a été classé, mais sa priorité de 50 le place sous les 100 de Flutterwave. Il n'aurait donc été appelé qu'après l'échec des deux connexions placées avant lui. CinetPay est passé en premier alors que sa priorité est aussi de 50, uniquement grâce à la règle : une connexion désignée par une règle correspondante est essayée avant l'ordre général, et Flutterwave, moins cher et qui réussissait bien récemment, n'est venu qu'ensuite. CinetPay a ensuite répondu que l'opérateur avait dépassé son délai. Cela ne dit rien sur le payeur. La cascade est donc passée à Flutterwave, qui a atteint le même portefeuille en moins d'une seconde.

Konsole montre pourquoi chaque paiement a été routé de cette façon. La réponse de l'API ne l'indique pas.

Ce qui arrête la cascade

La cascade n'est pas une politique de nouvelle tentative. C'est un seul parcours de la liste, dans l'appel POST /payments/{id}. Le tableau ci-dessous indique ce qui l'arrête ou la fait avancer.

Une carte saisie dans les champs propres à un prestataire (Stripe, une carte Paystack enregistrée) fait exception : seul le prestataire qui la détient peut la débiter. Elle va donc à cette connexion quel que soit le classement, et jamais à une autre. La fenêtre de paiement propre à un prestataire et un code ou une information que le payeur confirme ensuite restent de la même façon chez le prestataire qui les a ouverts (Waterfall & fallback).

Cascade et repli décrit les échecs qui font passer un paiement à la connexion suivante et le moment où une connexion est mise en pause.

Les deux façons dont le routage peut mal se terminer

Ces échecs sont différents et produisent des réponses distinctes. Le code de statut permet de les distinguer sans lire le message.

Une liste de candidats vide renvoie 422. Aucune tentative n'a eu lieu, donc aucune nouvelle tentative ailleurs n'est possible. Aucune de vos connexions ne peut actuellement traiter ce canal et cette devise, ou toutes celles qui le pourraient sont hors rotation.

Réponse · 422 Unprocessable Content

{

"code": 422,

"status": "Unprocessable Content",

"message": "No eligible payment provider found for this transaction.",

"errors": {

"channel": [

"No eligible payment provider found for this transaction."

]

}

}

Une liste parcourue jusqu'à son épuisement renvoie 402, tout comme un refus définitif unique tel qu'un rejet. error_code contient le motif exploitable du prestataire lorsqu'il en existe un. Ce n'est pas le cas lorsque tous les candidats échouent sans fournir de motif.

Réponse · 402 Payment Required

{

"code": 402,

"status": "Payment Required",

"message": "Insufficient balance",

"error_code": "insufficient_funds",

"transaction": {

"id": "trx_CSUGajfv9xh0XQ5wu2lx",

"status": "pending"

}

}

Notez le statut dans les deux cas. L'échec d'une tentative ne met pas fin au paiement. Celui-ci revient à pending et le payeur peut réessayer sur le même paiement avec un autre numéro ou une autre carte. Seul votre propre code décide si cette possibilité lui est proposée.

Ce que l'API indique et ce qu'elle n'indique pas

L'orchestration est volontairement invisible dans l'objet paiement. Connaître ses limites vous évite de chercher des champs qui n'existent pas.