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 sa construction, dans l'ordre suivi par le moteur.

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 ou une priorité, définie une seule fois, 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 routeur utilise le slug exact d'un opérateur, qui n'existe souvent 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 devient cm.mtn avant même le chargement du premier candidat. Une requête qui indique cm.mtn avec un numéro Orange est immédiatement refusée avec une réponse 422 qui précise l'incompatibilité, au lieu d'être redirigée discrètement.

Six filtres, puis un classement

L'admissibilité est décidée avant le calcul des scores. Chaque filtre donne une réponse simple par oui ou par non. Une connexion qui échoue à l'un d'eux n'apparaît simplement pas dans la liste.

Deux de ces filtres sont permissifs lorsqu'ils 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.

La priorité ordonne la liste, le score départage seulement les égalités

Cette distinction doit être parfaitement comprise, car ces deux étapes n'ont pas la même importance.

La priorité est absolue

Les candidats sont regroupés selon l'entier priority de votre connexion. Le groupe le plus élevé est essayé entièrement avant de passer au suivant. Une connexion de priorité 50 ne passe jamais devant une connexion de priorité 100, quels que soient son coût, la règle qui la désigne ou ses performances. La priorité est le seul contrôle qui n'est pas une suggestion.

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 palier. Leur ordre dépend entièrement du score ci-dessous.

Le score additionne trois éléments dans un même palier

Les scores identiques sont départagés par un tirage pondéré selon le weight de chaque connexion, 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. Le tirage décide seulement laquelle passe en premier. Les autres conservent leur ordre derrière elle comme solutions de repli.

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. Les quatre connexions aboutissent au même portefeuille MTN. Le classement décide laquelle le prend en charge.

Lisez cette représentation depuis le bas. NotchPay n'est jamais entré dans le classement, car son circuit était ouvert. PawaPay y est entré, mais sa priorité est de 50. Il n'aurait donc été appelé qu'après l'échec des deux connexions de priorité 100. Dans le palier 100, CinetPay est passé en premier avec 2550 points contre 225 pour Flutterwave, uniquement grâce à la règle. Flutterwave était moins cher et obtenait le meilleur score sur l'ensemble coût et télémétrie, mais pas sur la règle. CinetPay a ensuite expiré sur le chemin vers l'opérateur. 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.

Tous ces chiffres sont enregistrés pour chaque paiement. Vous les consultez dans Konsole, pas dans une réponse de l'API.

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}. Quatre événements peuvent l'arrêter.

Cascade et repli décrit en détail la classification des échecs et le coupe-circuit.

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.

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.

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.