UPI en profondeur : intégrer et exploiter. 6 chapitres et un QCM final.

Chapitre 1. Intent, collect, QR : mesurer la perte au lieu de la deviner.

Le statut final d'une transaction UPI se répartit sur trois champs distincts, remplis par trois acteurs différents. Le premier porte le verdict, le deuxième la cause vue par la NPCI, le troisième la cause vue par la banque du payeur. Leur décomposition constitue la mesure de référence d'une intégration mature, davantage que l'observation du parcours d'achat. Les fondre en un indicateur unique produit des tableaux de bord faux. L'archivage du seul verdict ne permet pas de distinguer une perte due au parcours du marchand d'une perte due à un établissement en difficulté.

Trois champs, trois émetteurs

La spécification NPCI publie à côté de chaque code une classification, BD pour un refus commercial et TD pour un refus technique. Cette étiquette décide de ce que le marchand a le droit de tenter ensuite. Un refus commercial vient du payeur ou de son compte, et le retenter à l'identique produit le même code. Un refus technique vient d'une indisponibilité, et une seconde tentative a du sens. La NPCI a communiqué à ses membres des cibles de moins de 1 % pour les refus techniques et de moins de 5 % pour les refus commerciaux.

L'instrumentation qui découle de cette lecture conserve à chaque tentative les trois champs de statut, la classification BD ou TD, l'identifiant de la banque du payeur et le mode d'initiation. Sans l'identifiant de la banque du payeur, les échecs du marchand ne peuvent pas être rapprochés de la publication mensuelle de la NPCI. La dégradation d'un seul établissement prend alors l'apparence d'une régression de l'application marchande. Les équipes qui pilotent leur taux d'autorisation en Inde confrontent chaque mois leur propre décomposition à celle du marché.

Chapitre 2. VPA : le mappeur central, la validation, le recyclage.

Une adresse virtuelle de paiement, ou VPA, désigne une entrée d'annuaire qui tient lieu de coordonnée de paiement, et non un compte. Le mappeur central de la NPCI relie chaque identifiant au fournisseur d'application qui le détient. Cet identifiant prend la forme d'une adresse nom@banque, d'un numéro de mobile ou d'un identifiant numérique. L'entrée d'annuaire change au fil du temps. La résolution précède donc chaque paiement. Traiter le VPA comme une donnée stable conduit à débiter la mauvaise personne, ou à perdre la trace du client.

Les codes du mappeur, et ce qu'ils imposent

1. NORMALISER A L'ECRITURE
   trim, minuscules, controle du separateur unique '@'
   'Ravi@okhdfcbank' et 'ravi@okhdfcbank' = UNE ligne de referentiel

2. NE JAMAIS INDEXER LE CLIENT SUR L'ADRESSE
   cle primaire = votre identifiant client
   l'adresse est un ATTRIBUT DATE, avec un historique
   colonnes utiles : valeur, date de validation, nom renvoye, statut

3. REVALIDER AVANT TOUT DEBIT DIFFERE
   une adresse validee il y a six mois n'est pas une adresse valide
   revalider avant : remboursement, reversement, reprise de mandat

4. AFFICHER LE NOM RENVOYE PAR LA BANQUE, PAS CELUI SAISI
   et exiger une confirmation explicite du client

5. SEPARER LES ECHECS DANS LES JOURNAUX
   resolution echouee   -> l'adresse n'a pas ete trouvee
   refus au paiement    -> l'adresse existe, le debit a ete refuse
   Les melanger rend le taux d'echec illisible.

Source des codes de mappage : NPCI, UPI Error and Response Codes v2.9,
section Central Mapper.

Chapitre 3. UPI AutoPay : UMN, seuils protocolaires, fenêtres d'exécution.

UPI AutoPay repose sur un objet distinct du paiement, le mandat, que désigne un UMN, le numéro de mandat unique. Ce mandat a un cycle de vie propre, qui va de la création à l'expiration en passant par l'exécution répétée, la modification, la pause et la révocation. Chaque étape porte ses propres codes. Lire l'exécution d'un mandat avec la grille d'un paiement ordinaire laisse donc de côté la moitié de l'information disponible. Les codes de mandat indiquent pourquoi un abonnement cesse d'être encaissable, et quel parcours le marchand doit déclencher.

Le seuil d'authentification est écrit dans le protocole

La règle réglementaire impose une authentification forte à la première échéance d'un mandat, puis dispense sous le seuil de ₹15 000. Deux codes de réponse de la spécification NPCI portent ce seuil. V3 signale un bloc de code confidentiel manquant pour une transaction supérieure à ₹15 000. V4 signale le même manque pour une transaction inférieure à ₹15 000 dont le numéro de séquence vaut 1. La règle est donc câblée dans les messages autant qu'écrite dans un texte, et l'intégration marchande la rencontre sous forme de code de refus. Une hausse tarifaire qui franchit le seuil produit donc V3 en production, dans le flux de paiement lui-même.

• Un mandat récurrent porte le code de finalité 14. La spécification impose alors un blocage de fonds à N, et les codes Q3 et V5 rejettent l'inverse.
• Le même code de finalité impose un mandat révocable, sauf pour le code catégorie marchand 7322, où les deux valeurs sont acceptées. Les codes Q4 et V6 sanctionnent l'écart.
• Le numéro de séquence identifie l'échéance dans le mandat. Il porte la logique de première exécution, et il sert de clé naturelle d'idempotence côté ordonnanceur.
• Un mandat s'exécute par un couple de messages distinct du paiement ponctuel. Vos journaux doivent donc classer les événements par UMN, pas seulement par identifiant de transaction.
• L'expiration d'un mandat est connue à l'avance : elle figure dans le mandat lui-même. Une équipe qui découvre VU en production a raté une alerte qu'elle pouvait poser des semaines plus tôt.

La conception du calendrier de facturation obéit à une seconde contrainte, distincte de ces bornes horaires. La pré-notification obligatoire avant chaque débit place la décision du payeur avant l'exécution, et non après le refus. Un abonnement indien suit donc deux horloges, celle de la notification appartenant à la relation client et celle de l'exécution appartenant au rail. Le modèle de données les distingue. Un refus exprimé la veille par le payeur et un rejet bancaire au moment du débit portent le même effet comptable et procèdent de deux causes opposées. Les réunir dans un indicateur unique prive l'équipe de rétention de la distinction entre un client qui se désengage et un client dont le compte a refusé le débit.

Chapitre 4. Webhooks, idempotence et discipline de sondage.

La spécification UPI prévoit trois issues pour une transaction, dont un état intermédiaire nommé DEEMED. Cet état désigne une transaction dont le crédit reste inconnu et dont le sort se règle ultérieurement. Sur UPI, une absence de réponse dans le délai attendu relève de cet état plutôt que de l'échec. Traduire un délai dépassé en « paiement refusé » fabrique donc une information que le rail n'a pas donnée. L'enchaînement qui suit associe un client débité, une commande annulée, un remboursement à instruire et une contestation qui arrivera de toute façon.

Le sondage de statut est une ressource réglementée

• La circulaire NPCI du 26 avril 2025, consacrée au cadrage de l'usage de l'API de vérification de statut, fixe le premier appel à 90 secondes après l'initiation de la transaction d'origine. Une communication ultérieure a ramené ce délai à 45-60 secondes.
• Le même texte plafonne à trois appels de vérification de statut, de préférence dans les deux heures suivant l'initiation. Au-delà, le membre consulte les fichiers de règlement plutôt que le commutateur.
• Une liste de codes vaut arrêt du sondage : recevoir l'un d'eux impose de considérer la transaction comme échouée et de cesser d'interroger.
• L'API de vérification n'accepte pas une transaction d'origine de plus de 90 jours : le code X09 sanctionne une date hors fenêtre. Passé ce délai, la vérité est dans les fichiers, pas dans une requête.
• Les Guidelines on the usage of UPI API du 21 mai 2025 plafonnent la consultation de solde à 50 par application, par client et par jour, et cantonnent certaines API d'inventaire aux heures creuses. Les échéances de mise en conformité étaient fixées au 31 juillet puis au 31 août 2025.

CLES ET LEUR PROPRIETAIRE
  ref_commande   -> VOUS. Choisie a l'ecriture, portee dans la requete,
                    renvoyee dans tous les evenements.
  txnId / RRN    -> LE RAIL. Inconnus tant que la transaction n'existe pas.
  UMN            -> LE RAIL. Identifie le mandat, pas l'echeance.
  seqNum         -> L'ECHEANCE dans un mandat. Cle naturelle d'idempotence
                    pour un ordonnanceur d'abonnements.

RECEPTION D'UN EVENEMENT
  1. verifier la signature AVANT de lire le corps
  2. cle d'unicite = (ref_commande, type_evenement, txnId)
     deja vue -> repondre 200 et SORTIR, sans rejouer d'effet metier
  3. accuser reception tout de suite ; le traitement metier est asynchrone
  4. n'appliquer une transition d'etat que si elle est AUTORISEE
     EN_ATTENTE  -> REUSSI | ECHOUE | INDETERMINE
     INDETERMINE -> REUSSI | ECHOUE
     REUSSI      -> (aucune)      <- un evenement en retard ne degrade pas
     ECHOUE      -> REUSSI        <- autorise : le rail peut confirmer tard

SONDAGE DE STATUT (bornes NPCI, circulaire du 26/04/2025)
  t = 90 s          premier appel
  puis 2 appels max, de preference sous 2 heures
  code d'arret recu -> ECHOUE, on arrete d'interroger
  au-dela           -> fichiers de reglement, plus d'appel unitaire
  transaction de plus de 90 jours -> refusee (code X09)

DUPLICATION
  U01 THE REQUEST IS DUPLICATE      -> votre requete etait deja partie
  DF / DT DUPLICATE RRN FOUND       -> collision de RRN cote beneficiaire
                                       ou cote remettant
  Dans les deux cas : NE PAS recreer la transaction. Interroger.

Une dernière pratique devient impraticable en Inde, celle d'interroger le solde du payeur pour anticiper un rejet. Le plafond de cinquante consultations par application, par client et par jour rend cette architecture intenable à l'échelle, et la NPCI a explicitement visé la surconsommation d'API comme cause d'indisponibilité du rail. L'information recherchée parvient de toute façon au marchand, par l'événement d'exécution puis par le fichier de règlement. L'architecture attendue consomme donc ces deux flux entrants, au lieu d'interroger le rail transaction par transaction.

Chapitre 5. Réconciliation UPI : cycles de règlement, drapeaux UDIR, contestations.

La réconciliation UPI repose sur des cycles de règlement quotidiens, sur les fichiers produits à chaque cycle et sur un système central de compensation qui tranche les écarts. Le modèle diffère de celui des réseaux carte, où interviennent une autorisation différée de la capture, une fenêtre de présentation et un relevé mensuel de réseau. Aucun de ces trois mécanismes n'existe sur UPI. Le rapprochement se conduit donc à trois niveaux, et chaque niveau a sa clé.

Lire les drapeaux UDIR

NIVEAU 1 : COMMANDE <-> TRANSACTION
  cle    : votre reference de commande, portee a l'initiation
  source : vos evenements + le rapport de l'agregateur
  ecart type : commande sans transaction (abandon), ou transaction
               sans commande (double soumission cote client)

NIVEAU 2 : TRANSACTION <-> CYCLE DE REGLEMENT
  cle    : identifiant de la transaction et RRN
  source : fichiers produits a chaque cycle
  depuis le 03/11/2025 : cycles 1-10 = autorisations,
                         cycles 11-12 = litiges (libelles DC1, DC2)
  ecart type : transaction reussie non reglee au cycle attendu
               -> ce n'est PAS un echec, c'est un decalage de cycle

NIVEAU 3 : REGLEMENT <-> ENCAISSEMENT BANCAIRE
  cle    : reference de versement de l'agregateur
  source : releve du compte de reversement
  ecart type : montant net different du brut attendu
               -> commissions, retenues, reprises de litige

REGLE DE CONCEPTION
  Ne jamais rapprocher sur (montant, horodatage). Sur un rail qui
  traite plus de vingt milliards d'operations par mois, la collision
  est certaine, pas probable.

Chapitre 6. Codes de refus NPCI et limites : la table de décision.

Une table de décision associe à chaque code de refus la suite à lui donner. Elle traite trois interrogations, l'origine du refus, l'intérêt d'une nouvelle tentative et l'opportunité d'informer le client. La spécification NPCI répond déjà à la première par la classification BD ou TD, qui sépare le refus commercial du refus technique. Les deux autres relèvent de la table elle-même. L'équipe d'exploitation la tient à jour au fil des évolutions de la spécification.

Les limites ne viennent pas toutes du même endroit

Un plafond UPI provient de trois sources distinctes, et le code de refus indique laquelle s'est appliquée. La NPCI fixe un cadre par catégorie, tandis que la banque du payeur applique ses propres bornes, que signalent ZU, Z8 et Z7. La couche de service UPI ajoute enfin ses propres plafonds de montant et de débit net. U02 et U03 les signalent. Rapporter tous les plafonnements à la NPCI conduit à demander une dérogation sans objet, alors que la limite atteinte est celle de l'établissement du client.

• Rangez vos codes en trois seaux : ne pas retenter (ZA, Z9, B3, U16), retenter plus tard (U28, U78, U67), corriger avant de retenter (XH, U02, ZH).
• Comptez les refus par banque de payeur, pas seulement en agrégat. Une dégradation d'un seul établissement se noie dans un taux global.
• Ne relancez jamais un client sur un code qui vous désigne : U77, X6 et ZN décrivent votre paramétrage d'acceptation.
• Conservez le code brut, jamais un libellé traduit. Un refus se rejoue des mois plus tard, et la table des codes évolue.
• Rapprochez chaque mois votre décomposition BD et TD de la publication NPCI par banque : c'est la seule référence externe disponible.

Une exploitation UPI mature se reconnaît à ce qu'elle sait faire de chaque refus. Elle établit, code par code et banque par banque, ce qu'elle peut corriger et ce qu'elle doit accepter. Un taux d'échec global agrège ces deux catégories. Il ne permet donc pas de les séparer. Le choix du mode d'encaissement, la politique de relance et la conception du calendrier de mandats découlent tous de cette table. Celle-ci s'établit avant l'ouverture du volume et se maintient avec la même discipline que le code applicatif.