La douleur d'une intégration API Oney apparaît rarement au moment où l'URL de paiement est générée. Elle arrive quand un dossier reste en `PENDING`, qu'une commande passe `FAVORABLE` mais n'est jamais confirmée, qu'un marchand expédie avant le bon retour API, ou qu'une annulation partielle devient incompréhensible pour la comptabilité.
Oney expose des briques précises pour le paiement fractionné et le crédit: génération d'un contexte de paiement, redirection vers le formulaire Oney, callback marchand, consultation de statut, confirmation quand le marchand est prêt à livrer, et annulation totale ou partielle.
Contrairement à ce que l'on croit souvent, le vrai sujet n'est pas seulement de proposer du 3x4x au checkout. Le vrai risque est de confondre acceptation Oney, validation client, préparation logistique et règlement marchand, alors que ces étapes ne portent pas la même décision.
Vous allez comprendre quoi cadrer en priorité: `split_payment_context`, `external_reference`, `merchant_guid`, `psp_guid`, `status_code`, `sub_status_code`, callback, `confirm`, `cancel`, limites d'appel et reprise support. Chaque objet doit raconter une preuve exploitable.
Pour poser ce cadre sans bricolage, notre accompagnement en intégration API peut relier Oney à votre checkout, votre ERP, votre OMS, votre comptabilité et vos outils support. Le sujet se rattache aussi à l'offre API paiement et à la page intégrateur Oney quand le besoin porte spécifiquement sur ce connecteur.
Pour qui l'intégration Oney devient critique
Oney devient critique pour les marchands qui vendent des paniers élevés, des produits à livraison différée, des biens soumis à vérification ou des offres où le paiement fractionné influence fortement la conversion. Le sujet dépasse vite le simple bouton de paiement.
Le besoin grandit quand une décision Oney déclenche ensuite la réservation de stock, la préparation logistique, un acompte, un remboursement, une annulation partielle ou un reporting financier. Un statut mal lu peut créer une promesse client impossible à tenir.
Le signal faible apparaît quand le support parle de paiement en attente sans savoir si le dossier attend le client, Oney, le marchand ou la livraison. Si `PENDING`, `FAVORABLE`, `FUNDED`, `REFUSED`, `ABORTED` et `CANCELLED` ne sont pas reliés à des actions, le run est déjà fragile.
1. Séparer contexte, statut et confirmation Oney
Comprendre le contexte comme une entrée de parcours, pas une preuve finale
Le service `POST /payments/v1.2/purchase/split_payment_context` permet de générer une URL de redirection vers la solution Oney pour le paiement fractionné, le 5x12x ou le crédit long selon le pays et le contrat.
Cette URL ouvre le parcours client, mais elle ne valide pas encore la commande. Le connecteur doit enregistrer le contexte, les références marchandes, le montant, la devise, les lignes, l'environnement et la version de payload.
La première règle de run consiste à garder un état interne dédié, par exemple dossier Oney initié. Cet état ne doit ni préparer la livraison, ni créer une écriture définitive, ni rassurer le support avec un faux succès.
Faire de la référence externe la clé métier du dossier
Les services de statut, confirmation et annulation utilisent notamment `psp_guid`, `merchant_guid` et la référence marchande. Cette valeur correspond à `purchase.external_reference`, et elle devient la clé naturelle de rapprochement côté marchand.
Cette référence doit être stable, unique et visible dans les outils métier. Elle ne doit pas être reconstruite depuis un panier temporaire ou une session front, car elle servira à relire le dossier quand un statut revient en retard.
Un mapping robuste relie référence externe, commande interne, montant, pays, produit Oney, statut, sous-statut, callback, confirm, cancel et journal de reprise. Sans cette table, chaque incident devient une enquête manuelle.
Ne pas confondre acceptation Oney et ordre de livrer
Le statut `FAVORABLE` signifie qu'Oney accepte le paiement et attend la confirmation du marchand prêt à livrer. Il ne doit pas être traité comme une transaction totalement terminée.
Le statut `FUNDED` indique que la transaction est complétée, avec débit client initial et financement marchand selon le flux de confirmation. Le SI doit donc séparer acceptation, confirmation et règlement.
La contre-intuition utile est là: une commande favorable peut encore être dangereuse si le stock, l'expédition ou le délai de confirmation ne sont pas maîtrisés. Le bon connecteur sait attendre sans perdre la vente.
2. Créer le split_payment_context sans panier fragile
Envoyer un panier et une livraison cohérents avec la décision de financement
Le payload Oney contient notamment des données d'achat, de montant, de devise, de livraison, de client, de navigation et de contexte marchand. Ces données alimentent un parcours financier, pas seulement une page de redirection.
Le montant doit rester cohérent avec le panier final, les frais, les remises, les acomptes ou moyens de paiement complémentaires. Un écart entre panier, demande Oney et commande ERP produira une reprise coûteuse.
Le connecteur doit donc figer la version du panier avant la génération d'URL. Si le client change une adresse, une ligne de panier ou une remise après le contexte, le SI doit relancer un contexte propre plutôt que bricoler une correction aval.
Adapter le parcours au pays et au produit Oney réellement disponible
Les produits Oney varient selon les pays: 3x4x, 5x12x, Paylater, crédit long, carte Oney ou autres produits selon les contrats et disponibilités locales. L'API demande aussi un header pays partenaire.
Un connecteur international ne doit donc pas afficher la même offre partout. Il doit relier pays, devise, type de produit, contrat marchand, montant et message client pour éviter une promesse impossible.
La matrice minimale contient pays, canal, montant minium, produit autorisé, langue, devise, champ obligatoire, page de succès, page d'échec et URL serveur. Cette matrice doit être pilotable par le métier.
Garder les URLs de navigation et de réponse serveur sous contrôle
Les parcours Oney utilisent des URLs de retour et de réponse serveur. La page de succès ou d'échec informe le client, mais le serveur marchand doit aussi recevoir ou récupérer le statut pour fiabiliser la commande.
La règle de sécurité est simple: un retour navigateur ne confirme jamais seul le paiement. Il peut mettre à jour l'interface, mais la décision métier doit passer par callback, consultation de statut et état interne.
Cette discipline évite les confirmations prématurées. Elle protège aussi les cas où le client ferme le navigateur, revient plus tard, ou obtient une réponse Oney après une revue plus longue.
3. Lire PENDING, FAVORABLE et FUNDED correctement
Classer les statuts Oney comme des décisions opérationnelles
Les statuts documentés comprennent notamment `PENDING`, `FAVORABLE`, `FUNDED`, `REFUSED`, `ABORTED` et `CANCELLED`. Certains flux mentionnent aussi `TO_BE_FUNDED` selon les versions, les produits et les parcours contractuels.
Chaque statut doit déclencher une action différente. `PENDING` indique une attente, `FAVORABLE` une acceptation à confirmer, `FUNDED` une transaction terminée, `REFUSED` un financement refusé, `ABORTED` un timeout et `CANCELLED` une annulation.
Le back-office doit montrer la traduction métier, pas seulement le code. Une commande peut être en attente client, en attente Oney, prête à confirmer, financée, annulée ou refusée, et ces états n'ont pas le même impact support.
Exploiter sub_status_code pour comprendre les attentes PENDING
Oney a ajouté `sub_status_code` sur `get_status` et callback pour donner plus d'information quand un paiement est en `PENDING`. Les exemples documentés incluent des attentes liées au KYC, à un dossier préaccepté ou à l'analyse Oney.
Cette information change la conduite du support. Une attente de validation client ne se traite pas comme une attente d'analyse Oney, et un dossier préaccepté ne se lit pas comme une commande refusée.
Si 15 dossiers restent en `PENDING` plus de 2 jours avec le même sous-statut, alors la priorité est à clarifier le message client et le routage support, car la charge opérationnelle devient déjà mesurable.
Ne jamais expédier sur un statut ambigu
L'expédition doit rester liée à une preuve compatible avec le flux Oney. Le statut `FAVORABLE` appelle une confirmation marchand, tandis qu'un `PENDING` ou un retour navigateur ne suffit pas à libérer la commande.
Le risque est de traiter le financement comme une carte bancaire classique. Oney porte un parcours de crédit ou de paiement fractionné avec temporalité propre, revue possible et statut de dossier.
Le bon runbook dit clairement quoi préparer, quoi bloquer, quoi communiquer et quoi reprendre. Cette séparation évite de promettre une livraison quand la décision financière n'est pas encore exploitable.
4. Confirmer seulement quand la livraison est prête
Appeler confirm au moment où le marchand peut livrer
Le service `confirm` doit être utilisé quand le partenaire est prêt à expédier les marchandises. Oney indique que cette étape paie le partenaire selon le montant demandé et débite le client de la première échéance.
La consigne importante est d'expédier uniquement après réception d'une réponse HTTP 200 sur l'appel confirm. Une confirmation envoyée mais non acceptée ne doit pas libérer la commande en logistique.
Le connecteur doit donc relier confirm, préparation, stock, colis, montant, références d'articles et propriétaire métier. Si la préparation échoue, la confirmation doit attendre ou être annulée selon le cas.
Respecter la fenêtre de confirmation depuis FAVORABLE
La documentation Oney indique une fenêtre de 21 jours pour confirmer une commande depuis le statut `FAVORABLE`. Ce délai transforme le statut favorable en compte à rebours opérationnel, pas en validation définitive.
Un marchand avec des délais fournisseurs ou une expédition différée doit surveiller cette fenêtre. Si la livraison n'est pas prête assez tôt, le support et la logistique doivent le savoir avant que le dossier ne parte en timeout.
Le tableau de bord utile affiche date de passage `FAVORABLE`, délai restant, owner, prochaine action, motif de blocage et risque client. Sans cela, les commandes favorables vieillissent silencieusement.
Éviter les confirmations en batch trop agressives
Oney conseille de prévoir un délai entre les appels si des confirmations sont envoyées en batch afin d'éviter des erreurs de timeout. Cette recommandation doit devenir une règle de batch, pas un souvenir de documentation.
Le batch confirm doit respecter rate limit, backoff, traçabilité, reprise et journal des erreurs. Une file mal réglée peut transformer un flux de commandes prêt à partir en rafale d'échecs techniques.
Le bon arbitrage consiste à privilégier un batch plus lent mais explicable. La logistique reçoit alors une décision fiable, la finance une preuve cohérente, et le support un délai qu'il peut annoncer.
5. Annuler sans casser acomptes et échéancier
Distinguer annulation totale, fraude et annulation partielle
L'API Oney permet d'annuler un achat avec un motif et un montant d'annulation selon le cas. Une annulation totale, une fraude détectée et une annulation partielle ne produisent pas les mêmes effets métier.
Le payload peut porter un montant d'annulation et un indicateur lié au remboursement de la provision selon les situations. Le SI marchand doit donc conserver la raison, le montant, le statut avant appel et le statut après retour.
Une annulation partielle peut laisser le dossier dans son état précédent tout en modifiant les échéances client. Le support doit voir cette nuance, sinon il risque d'annoncer une annulation totale quand seul le panier a été ajusté.
Rapprocher cancel avec avoir, stock et décision client
L'annulation doit venir d'une décision claire: rupture de stock, retour client, suspicion de fraude, erreur de prix, impossibilité de livraison ou correction commerciale. Sans motif structuré, le flux devient difficile à relire.
Le connecteur doit lier annulation Oney, commande interne, avoir, stock libéré, notification client et trace comptable. Si l'un de ces éléments manque, le cas doit rester en quarantaine.
Dans un scénario de retour, si 6 annulations partielles restent sans avoir pendant 7 jours alors la priorité est à bloquer l'automatisation, car le seuil révèle un risque financier, un délai de clôture et une charge support mesurables.
Refuser les annulations sans preuve de dossier
Une demande de cancel sans référence externe, sans statut connu, sans montant cohérent ou sans owner métier doit être retenue. Cette retenue protège le client et le marchand contre les mouvements financiers impossibles à expliquer.
La file de quarantaine doit être visible, datée et assignée. Elle sépare les erreurs de payload, les décisions finance, les blocages logistiques et les cas support qui demandent une vérification humaine.
Le bon tableau de suivi ne compte pas seulement les annulations. Il montre annulations envoyées, acceptées, refusées, rapprochées, communiquées au client et réintégrées dans l'ERP.
6. Utiliser callback et get_status sans doublon
Traiter le callback marchand comme une notification de statut
Le callback Oney est une API fournie par le marchand qui permet à Oney de communiquer le statut d'une demande de paiement. Le marchand doit répondre `204` quand le statut est reçu correctement ou `500` si l'appel n'a pas été traité.
Le handler callback doit journaliser la référence externe, le statut, le sous-statut, l'identifiant de requête Oney et la décision interne. Il ne doit pas masquer un échec de traitement avec une réponse positive.
Cette rigueur évite un piège courant: répondre OK avant d'avoir réellement appliqué la décision métier. Un callback accepté mais non traité crée une dette silencieuse que le support découvrira plus tard.
Utiliser get_status comme rellecture et outil de reprise
Le service `get_status` permet de récupérer le statut d'un dossier à partir des identifiants PSP, marchand et référence. Il devient indispensable pour relire un dossier après incident, timeout, doute support ou callback manqué.
Le connecteur doit comparer le statut récupéré avec l'état interne. Si Oney dit `FUNDED` et que la commande reste en attente, la reprise doit corriger le SI. Si le SI dit expédié mais qu'Oney n'est pas confirmé, l'alerte doit bloquer l'écart.
Le get status ne doit pas devenir un polling brutal. Il doit être appelé avec cadence, backoff, limites d'usage, et seulement pour des dossiers qui ont une prochaine action ou une anomalie à résoudre.
Rendre callback et polling idempotents
Un même statut peut être vu par callback, par rellecture manuelle ou par batch de reprise. Le traitement doit être idempotent sur la référence externe et le statut pour éviter doubles notifications, doubles annulations ou doubles confirmations internes.
La clé de décision doit combiner référence externe, statut Oney, sous-statut, version interne et effet métier déjà appliqué. Si l'effet est déjà produit, le système journalise la réception sans rejouer la commande.
Cette discipline donne une reprise sûre. L'équipe peut relancer un statut, rejouer un callback ou corriger une file sans craindre de modifier deux fois la même commande.
7. Gérer pays, sécurité et rate limit Oney
Séparer API key, pays partenaire et environnement
Les appels Oney utilisent une authentification par clé API et des headers comme `X-Oney-Partner-Country-Code`, selon les services. Les identifiants `merchant_guid` et `psp_guid` sont liés au contrat et à l'environnement.
Le connecteur doit séparer staging, production, pays, produit et marchand. Une clé valide dans un pays ne prouve pas que le même produit est disponible ailleurs, ni que le même contrat autorise le même parcours.
La configuration doit donc être versionnée et observable: base URL, clé, pays, produit, marchand, PSP, devise, langue, seuils et URLs serveur. Sans cela, une erreur de paramétrage ressemble à un refus de financement.
Respecter les limites d'appel documentées
Oney documente des limites pour la Payment API, avec 240 requêtes par minute et 300 000 requêtes par jour, tout en précisant que ces limites peuvent changer. Le Marketing API a des volumes plus élevés, mais ce n'est pas le même usage.
En cas de dépassement minute, un HTTP 429 peut être retourné. En cas de dépassement journalier, un HTTP 403 peut signaler le blocage. Ces codes doivent déclencher backoff, alerte et réduction de cadence.
Le batch de statut ou confirm doit être conçu avec ces limites. Une reprise mal contrôlée peut saturer l'API, retarder les dossiers sains et compliquer le dialogue avec le support Oney.
Classer les erreurs par décision support
Les réponses d'erreur peuvent signaler paramètre manquant, clé invalide, quota dépassé, API inconnue, timeout, conflit de statut, erreur interne ou service indisponible. Le support ne doit pas recevoir ces codes bruts sans traduction.
Le bon mapping distingue erreur à corriger, erreur à rejouer, attente normale, refus client, blocage de configuration et incident fournisseur. Chaque famille a une action, un owner et une alerte différente.
Le diagnostic doit aussi isoler les causes périphériques: latence réseau, certificat TLS, proxy, DNS, session expirée, payload incomplet, pays mal configuré ou produit non activé. Cette granularité évite d'accuser Oney à tort.
8. Erreurs fréquentes à éviter sur Oney
Expédier sur FAVORABLE sans attendre le confirm accepté
La première erreur fréquente consiste à interpréter `FAVORABLE` comme un feu vert logistique définitif. Oney attend encore la confirmation du marchand prêt à livrer, et l'expédition doit suivre une réponse confirm acceptée.
Le symptôme apparaît quand une commande part en préparation alors que l'appel confirm échoue ou n'a jamais été joué. Le client croit l'achat terminé, la logistique agit, mais le financement n'est pas correctement clôturé.
La correction est nette: à bloquer tant que confirm n'a pas répondu HTTP 200, à corriger si la commande a déjà été libérée, à escalader si le délai de 21 jours approche, et à tracer le propriétaire logistique.
Laisser les PENDING sans sous-statut et sans owner
La deuxième erreur consiste à empiler les dossiers `PENDING` dans un statut générique. Sans `sub_status_code`, owner et prochaine action, le support ne sait pas si le client doit compléter un KYC, si Oney analyse le dossier ou si une reprise est nécessaire.
Le coût caché se voit dans les paniers élevés: appels support, relances confuses, annulations prématurées, stock réservé trop longtemps et perte de conversion. Un dossier en attente n'est pas un incident si la prochaine action est claire.
Le bon réflexe consiste à router chaque PENDING selon son sous-statut, sa durée, son montant, son pays et son canal. Une attente client ne se traite pas comme une revue Oney ou un blocage technique.
Annuler partiellement sans rapprocher l'échéancier
La troisième erreur arrive après les premiers retours. Une annulation partielle est envoyée, mais l'avoir interne, le stock, le statut client et l'échéancier Oney ne sont pas relus ensemble.
Le risque n'est pas seulement financier. Un client peut voir une mensualité recalculée, le support une commande encore active, et la comptabilité un avoir manquant. La divergence devient visible trop tard.
La réponse opérationnelle est de retenir l'annulation si le montant, la référence, le motif, l'avoir et le statut de dossier ne sont pas cohérents. La vitesse de refund ne doit pas détruire la preuve de run.
Sortir les dossiers retenus avec une preuve lisible
Une revue hebdomadaire des cas retenus permet de distinguer anomalie isolée, défaut de paramétrage, manque documentaire, retard logistique et règle financière à formaliser. La file de quarantaine devient alors un outil de pilotage.
La méthode la plus fiable consiste à exiger trois preuves avant de sortir un dossier de quarantaine: statut Oney relu, écriture interne cohérente et décision support compréhensible. Si l'une manque, le connecteur doit conserver le blocage, enrichir le journal et proposer une action limitée plutôt qu'une correction silencieuse.
Ce filtre évite les reprises héroïques en fin de mois. Les équipes voient pourquoi une annulation partielle reste retenue, quel montant est encore exposé, quelle commande attend une confirmation et quel propriétaire doit trancher avant toute communication client.
9. Plan d'action pour livrer Oney sans dette
Prioriser les décisions avant les services API
Le plan d'action commence par les décisions qui changent le run. Il faut savoir ce qui initie le dossier, ce qui confirme l'acceptation, ce qui autorise la livraison, ce qui déclenche une annulation et ce qui clôture le financement.
- D'abord, figer les sources de vérité pour panier, référence externe, statut Oney, sous-statut, confirm, cancel, ERP et support.
- Ensuite, écrire les contrôles bloquants sur montant, pays, devise, délai de 21 jours, réponse HTTP 200, owner et statut interne.
- Puis, instrumenter callback, get_status, retries, files de quarantaine, backoff, alerting et runbook avant d'ouvrir les volumes.
- En priorité, valider les cas qui changent la marge, la livraison, l'acompte client, l'annulation ou une écriture financière.
- À différer, les dashboards secondaires qui ne réduisent ni délai support, ni divergence de statut, ni reprise manuelle.
- À refuser, toute expédition ou annulation qui ne peut pas montrer référence externe, statut, owner, montant et preuve de traitement.
Cette feuille de route oblige chaque service API à produire une décision, une preuve et une consigne support. Elle évite qu'une URL générée ou un statut favorable soit confondu avec une commande totalement exploitable.
Elle fournit aussi une cartographie stable: référentiel de statuts, nomenclature d'erreurs, matrice de criticité, journal d'arbitrage, registre d'exceptions, ownership applicatif, cadence de revue, critères d'escalade et schéma de payload versionné.
Le cadrage doit se lire comme une séquence d'arbitrages opérationnels, pas comme une liste de routes techniques. Chaque étape doit nommer le système qui décide, le système qui applique, la preuve attendue, le délai maximal et le responsable qui reprend si Oney ne renvoie pas l'état attendu.
Construire un runbook relié aux seuils de décision
Le runbook doit transformer les seuils en actions. Si un dossier reste PENDING, il faut savoir qui relance. Si un confirm échoue, il faut bloquer la livraison. Si un cancel manque d'avoir, il faut retenir le remboursement.
Si 10 commandes favorables restent sans confirm pendant 3 jours alors la priorité est à bloquer l'élargissement, parce que le délai logistique, le risque client et la charge support sont déjà visibles.
Les décisions doivent être courtes: à valider, à corriger, à bloquer, à rejouer, à annuler ou à escalader. Une erreur Oney sans décision écrite devient une dette de run, même si elle est techniquement journalisée.
Mettre en place une supervision lisible par commerce et finance
La supervision Oney doit relier les événements techniques aux conséquences métier. Un dashboard utile montre contextes générés, dossiers PENDING, dossiers FAVORABLE, confirms acceptés, cancels retenus, dossiers FUNDED et callbacks non traités.
- À faire dès la première version: afficher référence externe, statut, sous-statut, date FAVORABLE, délai restant, confirm, cancel et dernière décision métier.
- À valider avant go-live: retour navigateur, callback reçu, get_status relu, confirm accepté, cancel partiel et dépassement de rate limit simulé.
- À bloquer en production: confirm non accepté, PENDING sans owner, status inconnu, cancel sans avoir, pays mal configuré et batch sans backoff.
- À corriger pendant les 30 premiers jours: messages support ambigus, callbacks tardifs, files de quarantaine trop pleines et écarts ERP.
Cette mise en oeuvre rend le connecteur exploitable. Les entrées, sorties, dépendances ERP, seuils, owners, files de reprise, règles de rollback, contrats de payload et métriques de monitoring sont visibles avant que le volume ne rende les écarts plus coûteux.
La finance doit pouvoir isoler les dossiers qui ont changé de montant, reçu une annulation partielle ou attendu une confirmation trop longtemps. Le commerce doit voir les ventes sauvées, les ventes perdues et les ventes retenues, afin de piloter Oney comme un levier de conversion maîtrisé.
10. Tester un scénario panier élevé
Rejouer le flux nominal de bout en bout
Prenons un marchand qui vend un produit à panier élevé avec livraison planifiée. Le flux nominal génère un `split_payment_context`, redirige le client, reçoit une évolution de statut, passe `FAVORABLE`, confirme quand le colis est prêt, puis observe `FUNDED`.
Le test doit prouver plus qu'une redirection réussie. Il doit montrer la référence externe, le montant, le pays, le statut, le sous-statut, la réponse confirm, la décision logistique et la trace support.
Le bon résultat est une chronologie lisible dans le back-office. Le support doit pouvoir répondre sans ouvrir le code: où en est le dossier, quel statut Oney fait foi, quelle opération a été tentée et quelle preuve manque encore.
Simuler un PENDING qui dure et un FAVORABLE proche du délai
Le cas d'attente est plus important que le cas nominal. Il faut simuler un `PENDING` avec sous-statut, puis un `FAVORABLE` qui approche la limite de confirmation sans marchandise prête à partir.
Ce scénario doit produire une décision claire: relance client, attente Oney, blocage logistique, annulation contrôlée ou escalade. Le client ne doit pas recevoir un message vague de paiement refusé si le dossier est encore en cours.
La trace attendue contient date d'entrée en statut, owner, prochaine action, seuil de relance, message client, consigne support et risque de conversion. Cette preuve limite les discussions entre commerce, finance et équipe technique.
Simuler confirm échoué, cancel partiel et reprise
Un deuxième scénario doit faire échouer l'appel confirm, puis vérifier que la livraison reste bloquée. Ensuite, il faut jouer un cancel partiel avec avoir interne et contrôler que le statut final reste compréhensible.
Le test se termine uniquement quand le support sait expliquer le cas sans logs bruts. Avant cela, la chaîne n'est pas prouvée: elle a seulement démontré que l'API répond dans le cas favorable.
Cette recette protège la finance et la logistique. Elle permet de savoir si les équipes pourront reprendre un cas réel sans tableur improvisé, sans capture d'écran isolée et sans intervention permanente d'un développeur.
11. Fixer les seuils de go-live Oney
Valider les familles qui coûtent vraiment en production
La recette doit couvrir les familles qui créent de la dette: pays mal configuré, contexte expiré, PENDING sans owner, FAVORABLE non confirmé, confirm en timeout, cancel partiel sans avoir, callback non traité et get_status divergent.
Chaque scénario doit produire une preuve lisible par une personne hors projet. Cette exigence économise les heures perdues quand un incident de financement doit être expliqué au commerce, à la finance, au support et à la logistique.
Le seuil minimal de go-live peut être strict: zéro livraison sans confirm accepté, zéro PENDING sans owner, zéro cancel sans référence interne, zéro callback positif non traité, et aucun statut support impossible à expliquer.
Dans un scénario de reprise, si 4 callbacks reçus restent non appliqués pendant 2 jours alors la priorité est à corriger le handler, car le seuil révèle un risque de stock, un délai client et une dette support déjà mesurables.
Séparer acceptation technique et acceptation métier
Un HTTP 200 sur confirm prouve que l'appel a été accepté, mais l'acceptation métier doit vérifier stock, livraison, facture, message client et état ERP. Un HTTP 204 sur callback prouve une réception, pas forcément une décision complète.
Cette séparation évite une erreur classique: valider la mise en production parce que les endpoints répondent. Un connecteur peut être techniquement vert tout en laissant une dette énorme si personne ne sait expliquer un PENDING ou un cancel.
Le comité de lancement doit donc lire deux tableaux: succès API et décisions métier. Si les décisions métier ne sont pas lisibles, le lancement doit rester limité à un pays, une catégorie produit ou un canal plus court.
Prévoir un rollback qui ne supprime pas tout Oney
Le rollback Oney ne signifie pas forcément couper le moyen de paiement. Il peut consister à suspendre les confirms automatiques, réduire les pays ouverts, bloquer les cancels partiels ou revenir à un mapping de statut précédent.
Le seuil de rollback doit être écrit avant le lancement. Plusieurs confirms échoués sur une journée, une file de PENDING non routés ou une hausse de callbacks non traités doivent déclencher un retour au mode contrôlé.
Cette préparation protège la conversion sans sacrifier la fiabilité. L'équipe garde les flux prouvés, ferme les flux douteux et corrige la cause, au lieu de choisir dans l'urgence entre tout laisser ouvert et tout arrêter.
12. Organiser support, runbook et amélioration
Donner au support une fiche orientée référence externe
Le support doit disposer d'une fiche centrée sur la référence externe. Elle affiche pays, produit Oney, statut, sous-statut, date de passage `FAVORABLE`, confirm, cancel, dernier callback, dernière rellecture et action autorisée.
La fiche doit distinguer les messages client des causes techniques. Un `PENDING` KYC ne s'explique pas comme un refus, un confirm timeout ne se traite pas comme un dossier annulé, et un cancel partiel ne signifie pas toujours annulation totale.
Cette documentation doit être testée avec une personne hors projet. Si elle ne peut pas traiter un cas simple en moins de quinze minutes, le connecteur fonctionne peut-être, mais il n'est pas encore exploitable.
Suivre les trente premiers jours avec peu de métriques mais les bonnes
Les trente premiers jours doivent mesurer la qualité de décision: contextes générés, PENDING par sous-statut, FAVORABLE sans confirm, FUNDED, REFUSED, ABORTED, CANCELLED, callbacks non traités et tickets support récurrents.
Le suivi peut segmenter les irritants par pays, produit, catégorie, montant, terminal, navigateur, transporteur, délai fournisseur, motif SAV, numéro d'avoir, cohorte client, campagne d'acquisition et durée de résolution.
Une revue courte chaque semaine suffit si elle produit des décisions. Il faut corriger un mapping, clarifier un statut, ajouter une alerte, enrichir une fiche support ou refuser une automatisation. Une revue qui ne décide rien signale des métriques trop décoratives.
Le meilleur signe de maturité n'est pas l'absence totale d'anomalies. C'est la capacité à expliquer chaque anomalie, à la relier à un owner et à réduire progressivement les cas qui exigent une intervention technique.
Améliorer Oney à partir des preuves de production
Les améliorations doivent partir des symptômes observés. Si les PENDING durent trop longtemps, il faut relire les sous-statuts et le message client. Si les confirms échouent, il faut revoir batch, stock et backoff.
Cette méthode évite les refontes prématurées. Une intégration Oney peut être solide sur la redirection, mais faible sur la confirmation. Elle peut aussi être robuste sur les statuts, mais mal comprise par la logistique.
La feuille de route doit rester courte: une règle de statut, une preuve support, une reprise automatique ou une alerte financière. Tout ce qui ne réduit ni le risque, ni le délai de traitement, ni le coût support peut attendre.
Questions fréquentes sur l'API Oney
Pourquoi distinguer FAVORABLE et FUNDED dans Oney? `FAVORABLE` indique qu'Oney accepte le paiement et attend la confirmation du marchand. `FUNDED` indique que la transaction est terminée. Le SI doit donc séparer acceptation et clôture.
Quand faut-il appeler confirm? Le service confirm doit être appelé quand le marchand est prêt à livrer. La livraison doit rester bloquée tant que l'appel confirm n'a pas reçu la réponse attendue.
Comment gérer les dossiers PENDING? Les dossiers PENDING doivent être routés avec `sub_status_code`, durée d'attente, owner et prochaine action. Une attente client ne se traite pas comme une analyse Oney ou un blocage technique.
Dawap peut-il accompagner ce type d'intégration API? Oui. Dawap peut cadrer le mapping, développer le connecteur, sécuriser les clés, écrire les reprises, instrumenter les preuves support et relier Oney au checkout, à l'ERP, à l'OMS et à la comptabilité.
Guides complémentaires après Oney
Approfondir les architectures de paiement API avant le choix final
La ressource paiement API aide à replacer Oney dans une architecture PSP plus large. Elle clarifie les responsabilités entre checkout, financement, confirmation, annulation, rapprochement et support.
Elle devient utile quand Oney cohabite avec carte bancaire, PayPal, Stripe, Adyen ou un PSP historique. Le marchand peut alors comparer les statuts, callbacks, annulations et preuves de règlement au même niveau d'exigence.
Cette comparaison aide aussi à choisir les abstractions mutualisables. Les libellés support, journaux d'audit, files d'anomalie et tableaux financiers peuvent rester communs, tandis que les contrôles propres à Oney restent isolés.
Sécuriser les doublons entre callback, polling et reprise
La ressource idempotence API complète directement ce sujet. Elle aide à éviter doubles confirmations, doubles annulations, doubles mails et doubles écritures quand un même statut est rejoué.
Elle est particulièrement pertinente pour Oney, parce que callback et get_status peuvent raconter le même dossier. Le traitement doit savoir reconnaître un événement déjà appliqué et journaliser sans rejouer l'effet métier.
Elle donne enfin un vocabulaire de verrouillage utile: clé naturelle, effet irréversible, rejouabilité, concurrence, journal d'exécution et compensation. Ces notions évitent de confondre réception multiple et erreur fonctionnelle.
Piloter callback, get_status et incident Oney
La ressource webhook ou polling API aide à décider quand traiter le callback Oney, quand compléter par `get_status` et quand maintenir une commande en attente sans confirmer trop tôt livraison, facture ou financement.
Si une confirmation, une annulation, un statut favorable ou un lot de dossiers Oney devient ambigu, le runbook d'incident API donne le cadre pour geler le bon périmètre, choisir l'owner et reprendre uniquement les dossiers concernés.
Rapprocher Oney avec les écritures internes et les annulations
La ressource réconciliation API devient utile dès que statuts Oney, ERP, comptabilité et annulations racontent des états différents. Elle donne un cadre pour identifier la source qui doit trancher.
Elle complète la partie financement en donnant une méthode pour classer les écarts: statut collecté trop tôt, confirm manquant, cancel partiel mal ventilé, avoir absent ou commande expédiée sans preuve de confirmation.
Elle permet surtout de sortir du rapprochement artisanal par tableur. Les écarts sont qualifiés par période, nature, montant, référence et système propriétaire, ce qui rend la correction défendable auprès des équipes finance.
Préparer les flux financiers aval quand Oney déclenche la facture
La ressource facturation électronique API prolonge le sujet quand une commande Oney déclenche des écritures, des avoirs ou une facture. Elle aide à cadrer les dépendances entre confirmation, livraison et document financier.
Elle devient utile quand le financement ouvre une chaîne plus large: facture, avoir, statut de paiement, contrôle TVA et synchronisation ERP. Le statut favorable ne doit pas déclencher un document financier avant que la preuve serveur soit complète.
Pour passer du cadrage à l'exécution, la landing API paiement donne le cadre général, tandis que la page intégrateur Oney précise l'accompagnement possible sur ce connecteur.
Conclusion: brancher Oney sans dette de financement
Une intégration API Oney fiable commence par une chronologie respectée: contexte de paiement, redirection, callback, get_status, statut favorable, confirm, cancel éventuel et clôture métier. Chaque étape doit produire une preuve différente.
Les détails qui font la différence ne sont pas décoratifs: `split_payment_context`, `external_reference`, `merchant_guid`, `psp_guid`, `status_code`, `sub_status_code`, HTTP 204 callback, HTTP 200 confirm, rate limit et owner de reprise.
Le vrai coût d'un mauvais connecteur Oney apparaît rarement pendant le développement. Il apparaît quand une commande favorable n'est pas confirmée, quand un PENDING vieillit sans owner, ou quand une annulation partielle ne rejoint pas l'avoir.
Si vous devez intégrer Oney dans un SI e-commerce robuste, notre accompagnement Integration API peut cadrer le flux, développer le connecteur, sécuriser les reprises et donner au support les preuves nécessaires pour exploiter le financement sans dette cachée.
