Une intégration API Scalapay échoue rarement parce que le checkout ne s'ouvre pas. La douleur apparaît quand une commande est autorisée mais non capturée, quand un refund part sans référence lisible, quand un panier expiré reste visible côté boutique, ou quand la comptabilité ne sait plus quelle preuve relier au versement.
Scalapay documente un flux custom très concret: créer une commande avec `POST /v2/orders`, relire ses détails avec `GET /v2/payments/{token}`, puis finaliser avec `POST /v2/payments/capture`. Autour de ce noyau, le connecteur doit gérer delay, refund, reporting, idempotence, erreurs et reprise support.
Vous allez comprendre comment décider quoi créer, quoi relire, quoi capturer, quoi retarder, quoi rembourser et quoi bloquer. Le risque central est de laisser une dette de statuts se transformer en perte de marge, litige client ou correction manuelle répétée.
Pour poser ce cadre sans bricolage, notre accompagnement en intégration API peut relier Scalapay à votre boutique, votre ERP, votre OMS, votre comptabilité et vos outils support. Le sujet se rattache aussi à l'offre API paiement et à la page intégrateur Scalapay quand le besoin porte spécifiquement sur ce connecteur.
Pour qui Scalapay devient un sujet de run
Scalapay devient critique pour les marchands e-commerce qui vendent des paniers mode, beauté, lifestyle, équipement ou voyage avec un paiement fractionné qui pèse vraiment sur la conversion. Plus le panier moyen monte, plus une capture manquée coûte cher au support et à la finance.
La documentation Scalapay rappelle aussi un cadre commercial précis: les pays autorisés incluent notamment France, Italie, Espagne, Allemagne, Belgique, Pays-Bas, Portugal, Autriche, Finlande et plusieurs territoires ultramarins français, avec l'euro comme devise autorisée. Le connecteur doit donc filtrer pays, devise et produit avant de promettre le paiement.
Le signal de priorité apparaît quand un écart peut changer une livraison, une réservation de stock, une annulation, un remboursement, un reporting financier ou une promesse client. À ce moment, Scalapay n'est plus un bouton de paiement, mais un flux métier avec chronologie et preuves.
1. Créer une commande Scalapay sans panier fragile
Traiter le token comme une preuve à relier au panier
`POST /v2/orders` crée une commande Scalapay et retourne notamment un `token` ainsi qu'un `checkoutUrl` vers le paiement. Ce token n'est pas une décoration technique, car il devient la clé utilisée ensuite pour relire, capturer, retarder ou rembourser le dossier.
Le payload de création contient des objets structurants: `totalAmount`, `consumer`, `shipping`, `items`, `merchant`, mais aussi `billing`, `discounts`, `shippingAmount`, `taxAmount`, `merchantReference`, `type`, `product`, `frequency` ou `orderExpiryMilliseconds` selon le cas. Chaque champ doit être cohérent avec le panier réellement vendu.
La table interne doit donc lier token Scalapay, référence marchande, commande boutique, montant, devise, pays, produit, date d'expiration, version de panier et environnement. Sans ce mapping, la reprise d'une autorisation ou d'un refund devient une enquête manuelle.
Stabiliser montant, produit et redirections avant checkout
Le champ `product` peut cibler des produits comme `pay-in-3`, `pay-in-4` ou `later`, tandis que `type` peut notamment représenter un ordre `online`, `offline` ou `link`. Cette configuration doit venir d'une matrice métier, pas d'une condition codée à la volée.
Les URLs du bloc `merchant` servent à ramener le client vers le site après le parcours Scalapay. Elles ne doivent jamais devenir la seule preuve de décision, car un retour navigateur peut être interrompu, rejoué, ou arriver avant que le backend ait terminé son contrôle.
Une création fiable fige le panier avant redirection. Si le client modifie livraison, remise, pays, devise, produit ou lignes après la génération du token, le SI doit créer un nouveau contexte au lieu de corriger discrètement le dossier initial.
Ne pas confondre widget, éligibilité commerciale et ordre créé
La documentation custom demande aussi d'installer le widget Scalapay sur les points clés du parcours, notamment page produit, panier et checkout. Cette brique aide la conversion, mais elle ne remplace pas la création d'ordre ni le contrôle backend.
Le marchand doit séparer affichage commercial, disponibilité pays, produit BNPL, création d'ordre et décision financière. Un widget visible sur une fiche produit ne prouve pas que le panier final respecte devise, pays, montant, données client et contrat actif.
Le cadrage utile relie donc affichage front, matrice d'activation, création du token, journal d'audit et message support. Cette séparation évite de promettre Scalapay dans un cas que l'API ou le contrat ne doit pas accepter.
2. Lire l'autorisation avant de promettre la vente
Relire la commande avec GET payment avant effet métier
`GET /v2/payments/{token}` retourne les détails de la commande concernée. Cette lecture est indispensable pour vérifier l'état réel après le retour du client, surtout quand le front revient vite mais que le statut métier n'est pas encore exploitable.
La documentation Scalapay indique que cette étape permet de confirmer si le paiement a été autorisé pendant que l'algorithme effectue son contrôle. Le connecteur doit donc relire l'ordre avant de libérer une commande dans l'ERP ou la logistique.
Le bon modèle interne distingue ordre créé, client redirigé, autorisation observée, capture tentée, capture réussie, refund demandé et dossier rapproché. Cette chronologie permet au support de comprendre où le client se trouve réellement.
Traiter le retour navigateur comme un signal faible
Le retour navigateur est utile pour l'expérience client, mais il ne doit pas décider seul de l'état de commande. Un client peut fermer son onglet, perdre sa connexion, revenir deux fois ou atteindre une page de confirmation sans que la capture soit terminée.
Si un webhook Scalapay est disponible dans la configuration marchand, il doit être traité comme un événement de confirmation à rapprocher, pas comme une excuse pour abandonner la rellecture. La règle robuste reste de comparer événement reçu, token, montant et état relu.
Cette discipline protège les cas silencieux. Une commande peut être autorisée mais non capturée, expirée, remboursée ou absente du backend selon la plateforme, et le support doit disposer d'une preuve autre qu'une URL de retour.
Comprendre les différences entre plateformes e-commerce
Scalapay documente des comportements différents selon les plateformes. Sur WooCommerce et PrestaShop, une commande peut être créée avant redirection et rester visible même si le paiement n'est pas terminé, ce qui impose une reprise propre des expirations.
Sur Magento 2 et Shopify, la commande peut au contraire être créée après le retour réussi du client. Une interruption pendant la redirection peut donc produire un autre type d'écart, avec moins de visibilité côté back-office marchand.
Une intégration custom doit choisir explicitement sa règle. Il faut savoir si la boutique crée l'ordre avant checkout, après autorisation, après capture ou après une étape intermédiaire, puis aligner OMS, stock, mails et facturation sur cette décision.
3. Capturer, retarder ou annuler avec preuve
Capturer uniquement quand l'autorisation est exploitable
`POST /v2/payments/capture` capture le paiement associé à l'ordre. Scalapay précise que le montant est déduit du compte utilisateur et transféré au compte marchand, avec possibilité de capturer jusqu'au total spécifié pendant la création.
La capture accepte notamment le `token`, un montant et éventuellement une nouvelle `merchantReference`. Elle documente aussi un header `Idempotency-Key`, utile pour rejouer une tentative échouée sans créer un effet métier multiple.
Le connecteur doit donc bloquer la livraison tant que la capture n'a pas produit une preuve acceptée. Une autorisation seule ne suffit pas si la règle métier exige que la première charge soit réellement déclenchée avant préparation.
Utiliser delay quand le stock ou la livraison imposent une attente
`POST /v2/payments/{token}/delay` permet de demander une capture différée. Scalapay indique que l'échéancier de paiement client est créé, mais que les fonds ne sont pas réglés tant que l'appel de capture n'a pas été effectué.
Le champ `authorizationExpiryMilliseconds` porte la durée de validité de l'autorisation. La documentation montre une valeur de 432000000 millisecondes pour cinq jours, et précise que les autorisations restantes sont automatiquement annulées une fois l'expiration atteinte.
Cette option doit être pilotée par le métier. Si un produit attend un fournisseur, si un voyage dépend d'une confirmation, ou si un panier contient une rupture partielle, delay doit être relié à une décision visible et à un compte à rebours support.
Prévoir l'annulation avant que l'autorisation expire
Une capture différée peut devenir dangereuse si personne ne surveille l'expiration. Le SI doit afficher token, date d'autorisation, délai restant, montant exposé, statut logistique, owner et prochaine décision avant que le dossier bascule sans explication.
Le risque principal n'est pas seulement financier. Une commande peut sembler sauvée côté commerce alors qu'elle se dirige vers un échec de capture, une annulation automatique ou un dossier client impossible à expliquer simplement.
Si 12 commandes différées approchent de l'expiration dans les 24 heures sans owner, la priorité est à bloquer l'élargissement du flux. Le problème est déjà opérationnel, même si l'API continue de répondre correctement.
4. Rembourser sans casser l'échéancier
Relier refund Scalapay, avoir interne et statut client
`POST /v2/payments/{token}/refund` rembourse un paiement exécuté. Scalapay documente un `refundAmount`, une `merchantRefundReference` et un header `Idempotency-Key`, ce qui donne les trois points d'ancrage utiles pour montant, suivi et rejeu.
Le refund peut porter sur un retour, une annulation ou tout scénario où des fonds doivent être rendus au client. Le connecteur doit distinguer refund total, refund partiel, avoir interne, retour produit et message client.
La règle de prudence consiste à ne pas envoyer un refund si le montant, le token, la référence de remboursement, l'avoir et le statut de capture ne sont pas cohérents. La vitesse ne doit pas détruire la preuve financière.
Tracer les refunds partiels comme des événements irréversibles
Le paiement fractionné rend le remboursement partiel plus sensible qu'un simple ajustement de commande. Le client voit un échéancier, le support voit une demande de retour, la comptabilité voit un avoir, et Scalapay voit un montant à reverser.
Le journal doit donc conserver montant initial, montant remboursé, montant restant, motif, référence de refund, responsable, date, réponse API et lien avec l'avoir. Cette preuve sert autant au support qu'au rapprochement bancaire.
Si 8 refunds partiels restent sans rapprochement pendant 7 jours, alors le problème dépasse le service client. Il faut vérifier le mapping entre lignes de commande, avoirs, reporting Scalapay et écritures ERP avant d'automatiser davantage.
Séparer remboursement depuis portail et remboursement API
Scalapay indique qu'un refund peut aussi être traité depuis le Merchant Dashboard. Cette possibilité est utile en reprise, mais elle crée une dette si le SI marchand ne récupère pas ensuite l'événement ou le reporting correspondant.
Le runbook doit donc dire qui a le droit de rembourser depuis le portail, dans quels cas, avec quelle référence, et comment l'information revient vers ERP, support, logistique et comptabilité. Sinon, le portail devient une source parallèle.
Le bon compromis consiste à autoriser le portail pour les exceptions, mais à imposer une rellecture quotidienne des refunds et une justification métier. L'objectif n'est pas de bloquer les équipes, mais de garder une seule chronologie défendable.
5. Comprendre les statuts Scalapay utiles au support
Séparer Order Status et Capture Status
Scalapay distingue deux familles de statuts: `Order Status` et `Capture Status`. Cette séparation est essentielle, car une commande peut raconter un état client pendant que la capture raconte un état financier différent.
Les statuts d'ordre documentés incluent `pending`, `expired`, `refunded_not_charged`, `charged`, `partially_refunded` et `refunded`. Les statuts de capture incluent aussi `pending`, `captured`, `delayed` et `voided`, avec des effets opérationnels différents.
Le back-office ne doit pas afficher seulement ces codes. Il doit traduire chaque combinaison en action: attendre le client, relire l'autorisation, capturer, surveiller une expiration, enquêter sur un échec technique ou rapprocher un remboursement.
Lire pending, expired et refunded_not_charged sans panique
Un ordre `pending` correspond à une commande créée mais pas encore autorisée par le client. Scalapay précise qu'elle peut rester dans cet état pendant 40 minutes si elle n'est pas complétée, ce qui impose une gestion calme de l'attente.
Le statut `expired` correspond à une commande expirée sans autorisation. Ce n'est pas forcément une panne technique, parce que l'utilisateur peut avoir abandonné le parcours ou obtenu un refus bancaire que Scalapay ne détaille pas pour raisons de confidentialité.
Le statut `refunded_not_charged` est plus sensible, car Scalapay le rattache à des problèmes techniques lorsque l'ordre a été autorisé mais non capturé. Ce cas doit déclencher une alerte prioritaire, pas une simple clôture automatique.
Aligner les statuts portail avec les statuts SI
Dans le Merchant Portal, Scalapay affiche notamment des commandes Paid, Authorized, Refunded ou Partially Refunded. Les commandes `expired` et `refunded_not_charged` peuvent ne pas être visibles dans le backend portail, ce qui complique le diagnostic support.
Le SI marchand doit donc garder sa propre table de vérité, avec token, référence, état Scalapay, état interne, date de dernière rellecture et décision. Il ne doit pas dépendre uniquement d'une recherche manuelle dans le portail.
Cette table évite une mauvaise conclusion classique: le support ne voit rien dans le portail, donc il pense que la commande n'existe pas. En réalité, elle peut être expirée, non capturée ou créée dans un autre moment du parcours.
6. Traiter erreurs HTTP et idempotence proprement
Classer les erreurs par action métier, pas par stack technique
Scalapay documente des codes HTTP standard: `2XX` pour une requête acceptée, `4XX` pour une requête invalide ou incomplète, et `5XX` pour une erreur inattendue côté serveur. Cette classification doit être traduite en décisions opérationnelles.
Une réponse d'erreur peut contenir `errorCode`, `errorId`, `message` et `httpStatusCode`. Scalapay recommande de s'appuyer sur le code d'erreur et le code HTTP plutôt que sur le message lisible, qui peut évoluer dans le temps.
Le connecteur doit donc ranger chaque erreur dans une famille stable: payload à corriger, authentification à revoir, conflit à relire, tentative à rejouer, incident fournisseur à surveiller ou dossier à bloquer pour décision humaine.
Utiliser Idempotency-Key sur les effets sensibles
Les endpoints de création, capture, delay et refund documentent un header `Idempotency-Key`. Cette clé permet de réessayer une requête échouée sans multiplier l'effet métier, ce qui devient vital dès que le réseau ou le worker peut rejouer.
La clé doit être liée à l'effet voulu, pas seulement à la tentative HTTP. Capturer un token, retarder une autorisation ou rembourser un montant précis sont des effets différents, qui méritent des clés différentes et journalisées.
Le piège consiste à générer une nouvelle clé à chaque retry automatique. Le transport semble alors robuste, mais le métier peut recevoir deux captures, deux refunds, deux mails ou deux écritures internes pour une seule décision.
Sécuriser API key, merchant token et environnements
La mise en production Scalapay demande des identifiants fournis dans le Partner Portal, dont une clé de production mentionnée comme commençant par `sp_` et un merchant token selon les intégrations. Ces secrets doivent rester séparés par environnement.
Le connecteur doit isoler sandbox, production, pays, devise, produit, base URL, clé API, merchant token, droits applicatifs et rotation possible. Une confusion d'environnement peut produire des tests rassurants mais une mise en ligne inopérante.
La supervision sécurité doit montrer qui a utilisé quelle clé, sur quel environnement, pour quel endpoint et avec quel résultat. Cette trace est utile pour l'audit, mais aussi pour comprendre rapidement une erreur 401 ou une mauvaise activation.
7. Rapprocher orders, refunds et reporting
Utiliser le reporting orders pour réconcilier les transactions
`GET /v1/reporting/orders` permet de récupérer des ordres pour réconcilier transactions bancaires, orders et refunds dans Scalapay. Les paramètres documentés incluent `startDate`, `endDate`, `size` et `page`, avec une pagination pensée pour le volume.
Ce reporting ne doit pas rester un export occasionnel. Il doit alimenter une vérification régulière entre boutique, Scalapay, ERP, comptabilité et compte marchand, avec une période de contrôle alignée sur les clôtures financières.
Le rapprochement utile repère les captures absentes, montants divergents, orders inconnus, références manquantes, statuts expirés, remboursements non rapprochés et dossiers passés par le portail. Chaque écart doit obtenir un owner et une date de résolution.
Utiliser le reporting refunds comme contrôle de vérité
`GET /v1/reporting/refunds` récupère les refunds sur une période et sert aussi au rapprochement bancaire. Le endpoint accepte notamment dates de début et fin, taille de page et numéro de page, avec authentification par clé API Bearer.
Cette lecture devient cruciale quand un remboursement a été lancé depuis le portail, depuis un plugin ou depuis un flux API différent. Le SI doit absorber la vérité finale plutôt que supposer que son propre appel est le seul événement possible.
Une bonne routine de run compare refunds Scalapay, avoirs internes, lignes retournées, remboursements clients et écritures comptables. Les écarts doivent être classés par montant, ancienneté, canal, pays, référence et criticité support.
Retrouver un ordre par références quand le token manque
Le service de recherche par références permet de retrouver des ordres à partir de valeurs comme `orderToken`, `merchantOrderReference` ou `merchantProcessorReference`. Cet endpoint limite la dépendance à une seule clé perdue dans un incident.
Cette capacité est précieuse quand le support part d'un numéro de commande, quand l'ERP porte une référence processeur, ou quand un ticket arrive avec une capture du portail plutôt qu'un token complet.
Le modèle de données doit donc conserver plusieurs clés de corrélation. Token, référence marchande, référence processeur, commande interne et identifiant de ticket support ne racontent pas la même chose, mais ils doivent se rejoindre rapidement.
8. Erreurs fréquentes sur Scalapay
Croire qu'une autorisation vaut capture définitive
La première erreur consiste à traiter une autorisation comme une vente totalement finalisée. Scalapay demande une capture pour finaliser l'ordre, et le support merchant rappelle de vérifier que l'appel de capture existe au bon moment.
Le symptôme est connu: la boutique a promis la vente, la logistique a avancé, mais Scalapay n'a pas capturé correctement. Le dossier peut devenir `refunded_not_charged`, ce qui signale une anomalie technique plutôt qu'un simple abandon client.
La correction est nette: bloquer la préparation tant que la capture n'est pas prouvée, relire l'ordre si l'autorisation semble acquise, alerter si le délai d'expiration approche et conserver le owner de reprise dans le back-office.
Par exemple, si 10 commandes autorisées restent non capturées pendant 2 jours, alors la priorité est de stopper l'élargissement, car le seuil touche déjà la marge, la promesse logistique et le temps de résolution support.
Laisser les commandes expirées polluer le support
La deuxième erreur touche les plateformes qui créent l'ordre avant redirection. Une commande peut rester côté boutique alors que le client n'a pas terminé le paiement, ce qui donne au support une vente fantôme difficile à expliquer.
Le coût caché se voit dans les relances automatiques, réservations de stock, e-mails incomplets et demandes client ambiguës. Une expiration Scalapay n'est pas forcément une panne, mais elle devient un incident si la boutique ne sait pas la classer.
Le bon réflexe consiste à surveiller les ordres `pending` au-delà d'un seuil, les ordres `expired`, les retours navigateur incomplets et les commandes boutique sans capture. La fermeture doit être propre, tracée et compréhensible.
Rembourser sans rapprocher la ligne vendue
La troisième erreur arrive après le lancement, quand les retours produits se multiplient. Un refund part sur le bon token, mais l'avoir, le stock, la ligne de commande et le reporting Scalapay ne racontent pas exactement le même montant.
Le client voit un remboursement partiel, la finance cherche une écriture, le support parle d'une annulation, et l'ERP conserve une ligne encore active. La dette de preuve apparaît souvent plusieurs jours après le geste commercial.
La réponse opérationnelle est de retenir tout refund partiel qui ne peut pas montrer token, montant, référence de refund, avoir, ligne concernée et statut post-traitement. La file de quarantaine doit protéger la comptabilité.
Cas concret: si 5 refunds partiels dépassent 3 jours sans rapprochement, alors le bon arbitrage est de bloquer les remboursements automatiques suivants, car le seuil indique déjà une dette financière plus coûteuse que la validation manuelle.
Multiplier les retries sans clé d'effet stable
La quatrième erreur paraît technique, mais elle touche directement la marge. Un retry automatique sans clé d'idempotence stable peut rejouer une capture, un delay ou un refund alors que le premier appel a peut-être réussi côté Scalapay.
Le risque augmente quand un worker consomme une file, quand un timeout masque la réponse, ou quand une équipe relance manuellement depuis un outil interne. Sans journal d'effet, personne ne sait si le deuxième appel corrige ou double.
La méthode la plus fiable consiste à enregistrer l'intention avant l'appel, puis la clé, le payload, la réponse, la rellecture et la décision métier. Si l'une manque, la reprise doit rester contrôlée par un propriétaire identifié.
9. Plan d'action pour livrer le connecteur
Commencer par la chronologie métier
Le plan d'action commence par une chronologie stable: panier validé, ordre créé, redirection, retour client, lecture de l'ordre, capture, delay éventuel, refund éventuel, reporting et rapprochement. Chaque étape doit produire une preuve différente.
La question utile n'est pas quel endpoint développer en premier, mais quelle décision chaque endpoint autorise. Créer un ordre n'autorise pas la livraison, lire une autorisation ne clôture pas la vente, et capturer ne remplace pas le rapprochement.
Cette chronologie doit être lisible par commerce, logistique, support, finance et technique. Si une équipe ne sait pas expliquer où se trouve le dossier, le connecteur n'est pas prêt, même si tous les appels répondent en sandbox.
Le cahier de mise en oeuvre doit préciser entrées, sorties, responsabilités, owner, monitoring, seuils, journalisation, retry, idempotence, dépendances ERP, contrat de payload et règle de rollback. Sans cette granularité, la reprise dépend trop d'une personne experte.
- D'abord, figer la matrice pays, devise, produit, panier, référence marchande, URLs de retour et règles de création boutique.
- Ensuite, développer création, rellecture, capture, delay, refund, recherche par référence, reporting et journal d'effet idempotent.
- Puis, définir les blocages métier sur capture absente, expiration proche, refund incohérent, statut inconnu et divergence ERP.
- À valider avant volume, prouver les cas autorisé non capturé, expired, refunded_not_charged, refund partiel et ordre introuvable.
- À refuser, toute automatisation qui ne peut pas montrer token, montant, statut, propriétaire, clé d'idempotence et décision finale.
Dessiner le modèle de données de reprise
La table de reprise doit porter token, référence marchande, référence processeur, commande interne, statut d'ordre, statut de capture, montant, devise, produit, pays, clé d'idempotence, endpoint, dernière réponse et action suivante.
Elle doit aussi conserver les liens vers panier, avoir, ticket support, journal de worker et reporting financier. Cette granularité évite de traiter un incident Scalapay comme une simple ligne technique sans effet métier.
Si 20 dossiers nécessitent une reprise après les premiers tests, la priorité n'est pas d'ajouter un tableau de bord esthétique. Elle est de réduire les causes racines: mapping incomplet, capture tardive, idempotence instable ou consigne support absente.
- À afficher dans chaque dossier: token, référence marchande, statut d'ordre, statut de capture, montant, owner et prochaine action.
- À bloquer automatiquement: capture absente, refund sans avoir, expiration proche, clé d'idempotence manquante et divergence de reporting.
- À revoir chaque semaine: erreurs par endpoint, délais de reprise, volume de quarantaine, litiges clients et écarts comptables non résolus.
Mettre la supervision dans le quotidien des équipes
La supervision minimale affiche orders créés, `pending` anciens, `expired`, captures réussies, delays ouverts, expirations proches, refunds partiels, refunds non rapprochés, erreurs 4XX, erreurs 5XX et dossiers `refunded_not_charged`.
Chaque indicateur doit avoir un seuil et une action. Une courbe sans propriétaire ne protège pas le run, tandis qu'une alerte avec owner, délai, impact et runbook permet une résolution avant que le client ne relance.
Le tableau utile distingue conversion, risque financier, charge support et dette technique. Une augmentation des orders peut être une bonne nouvelle commerciale, mais devenir un risque si le ratio de captures ou de refunds non rapprochés se dégrade.
Une seconde fiche d'exécution doit détailler les entrées, sorties, responsabilités, owner, instrumentation, monitoring, runbook, file de reprise, seuils et contrat d'alerte. Cette fiche rend la supervision exploitable par une équipe qui n'a pas développé le connecteur.
10. Tester panier, capture et refund
Rejouer le flux nominal sans raccourci
Le test nominal doit créer un ordre avec panier complet, rediriger le client vers Scalapay, relire le token au retour, capturer le paiement, puis vérifier que la commande interne avance uniquement après la preuve de capture.
Il faut tester les champs qui feront mal en production: `merchantReference`, montant total, frais de livraison, taxe, lignes, pays, devise, produit, URLs, expiration et réponse de capture. Un checkout qui s'ouvre ne suffit pas.
Le bon résultat est une chronologie que le support peut lire sans aide technique. On doit voir l'heure de création, l'heure de retour, l'état relu, la capture, la clé d'idempotence et la décision logistique.
Simuler refus, expiration et capture manquée
Scalapay documente des cartes de test positives et négatives pour vérifier le parcours. Il faut les utiliser pour prouver les refus, expirations et retours incomplets, pas seulement pour chercher un paiement réussi.
Le scénario critique consiste à produire une commande autorisée mais non capturée, puis à vérifier la reprise. Le SI doit alerter, bloquer la livraison, relire l'ordre et éviter que le dossier devienne une promesse client non financée.
Cette recette doit inclure différences plateformes, redirection interrompue, session expirée, ordre absent du back-office et ordre visible mais non payé. Le support doit savoir quoi dire dans chaque variante.
Tester refund total, refund partiel et reporting
Le refund total vérifie le chemin simple, mais le refund partiel vérifie réellement la maturité du connecteur. Il oblige à relier ligne retournée, montant, référence de remboursement, avoir interne et état Scalapay après traitement.
Le test doit ensuite relire le reporting refunds et le reporting orders sur la période concernée. La preuve n'est pas complète tant que l'événement n'apparaît pas dans le rapprochement et dans la comptabilité interne.
Une recette solide se termine par un ticket support simulé. Une personne hors projet doit retrouver le dossier depuis une référence client, comprendre l'état, vérifier le remboursement et expliquer la prochaine action en moins de quinze minutes.
11. Fixer les seuils de go-live Scalapay
Choisir des critères qui protègent la vente et la finance
Le go-live doit être conditionné par des preuves, pas par une impression de fluidité. Il faut valider création d'ordre, rellecture, capture, delay, refund, recherche par référence, reporting, erreurs et reprise avant d'ouvrir largement.
Les critères utiles portent sur taux de capture, délai moyen de capture, nombre d'orders `pending` anciens, expirations, refunds non rapprochés, erreurs par endpoint, absence de doublons et capacité support à résoudre un cas simple.
La décision de lancement peut rester progressive. Un périmètre réduit sur un pays, un produit ou une catégorie vaut mieux qu'un déploiement large qui mélange conversion, retours produits et dette de rapprochement dès la première semaine.
Bloquer les anomalies avant d'élargir les volumes
Si une commande `refunded_not_charged` apparaît pendant la recette sans cause comprise, le lancement doit attendre. Ce statut indique une autorisation non capturée ou un problème technique, donc une faiblesse directe du flux critique.
Si les refunds partiels ne rejoignent pas les avoirs, le lancement doit attendre aussi. Le problème peut sembler limité au SAV, mais il deviendra financier lors de la clôture, quand les montants devront être justifiés.
Le même principe vaut pour les erreurs 401, 409 ou 5XX non classées. Tant que la réponse attendue n'est pas écrite dans le runbook, le connecteur dépend d'une personne qui sait improviser, ce qui ne tient pas en production.
Organiser une mise en production observable dès le premier jour
Le premier jour doit avoir une war-room légère avec commerce, support, finance et technique. L'objectif n'est pas de regarder tous les logs, mais de vérifier les décisions qui changent la vente, la livraison et le remboursement.
Les métriques doivent être lues plusieurs fois pendant les premières heures: orders créés, retours checkout, captures, delays, expirations, refunds et erreurs. Une dérive faible au début peut éviter une dette forte le lendemain.
La passation de fin de journée doit produire une liste courte: incidents clos, dossiers retenus, anomalies à corriger, seuils à ajuster et décision d'élargissement. Sans cette revue, le lancement ne capitalise pas sur ses preuves.
12. Organiser support et amélioration continue
Donner au support une fiche centrée sur le token
Le support doit disposer d'une fiche qui part du token Scalapay ou de la référence marchande, puis montre statut d'ordre, statut de capture, montant, produit, pays, date de création, capture, refund et dernière rellecture.
Cette fiche doit traduire les états. `pending` ne signifie pas la même chose que `expired`, `charged`, `partially_refunded` ou `refunded_not_charged`, et chaque statut doit conduire à une réponse client différente.
Une bonne fiche évite trois mauvais réflexes: demander au client de repayer trop vite, promettre une livraison sans capture, ou lancer un refund alors que le paiement n'a pas été capturé. Elle transforme les codes en consignes.
Suivre les trente premiers jours avec peu de métriques mais les bonnes
Les trente premiers jours doivent mesurer la qualité de décision: commandes créées, autorisations, captures, délais de capture, refunds, expirations, erreurs par endpoint, reprises manuelles, tickets support et écarts de reporting.
Il faut segmenter par pays, devise, produit, catégorie, canal, plateforme, terminal, moyen de livraison, délai fournisseur et montant. Cette segmentation évite de traiter un problème local comme une panne générale du connecteur.
Une revue courte chaque semaine suffit si elle produit des décisions concrètes. Ajouter une alerte, corriger un mapping, clarifier une fiche support ou fermer une automatisation dangereuse vaut mieux qu'un tableau exhaustif sans arbitrage.
Améliorer Scalapay depuis les preuves de production
Les améliorations doivent partir des symptômes réels. Si les captures tardent, il faut relire le moment de retour checkout. Si les refunds divergent, il faut revoir la relation entre lignes, avoirs et reporting.
Si les expirations polluent le support, il faut revoir la création de commande côté plateforme. Si les erreurs 409 montent, il faut vérifier concurrence, idempotence, retry et ordre des opérations.
La feuille de route doit rester simple: une règle de statut, une preuve support, une alerte financière ou une reprise automatisée. Tout ce qui ne réduit ni risque client, ni délai support, ni écart comptable peut attendre.
Questions fréquentes sur l'API Scalapay
Quel est le flux API Scalapay minimal? Le flux minimal crée une commande avec `POST /v2/orders`, relit les détails avec `GET /v2/payments/{token}`, puis finalise avec `POST /v2/payments/capture`. Le refund et le reporting complètent le run.
Pourquoi une commande autorisée peut-elle rester dangereuse? Une autorisation sans capture ne suffit pas à finaliser la vente. Scalapay signale notamment le cas `refunded_not_charged` quand un ordre a été autorisé mais non capturé correctement.
Comment gérer les refunds partiels? Il faut relier token, montant, `merchantRefundReference`, ligne retournée, avoir interne, réponse API et reporting refunds. Sans ce rapprochement, le support et la finance finissent avec deux histoires différentes.
Dawap peut-il accompagner cette 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 Scalapay au checkout, à l'ERP, à l'OMS et à la comptabilité.
Guides complémentaires après Scalapay
Approfondir les architectures de paiement API avant arbitrage
La ressource paiement API aide à replacer Scalapay dans une architecture PSP plus large. Elle clarifie les responsabilités entre checkout, autorisation, capture, refund, reporting et support.
Elle devient utile quand Scalapay cohabite avec carte bancaire, PayPal, Stripe, Adyen, Oney ou Klarna. Le marchand peut comparer statuts, captures, refunds et preuves de règlement au même niveau d'exigence.
Cette comparaison aide aussi à décider ce qui doit être mutualisé. Journaux d'audit, files de reprise, nomenclature d'erreurs et tableaux financiers peuvent être communs, tandis que les règles Scalapay restent isolées.
Sécuriser les doublons de capture et remboursement
La ressource idempotence API complète directement ce sujet. Elle aide à éviter doubles captures, doubles refunds, doubles mails et doubles écritures quand une tentative est rejouée.
Elle est particulièrement pertinente pour Scalapay, parce que les endpoints sensibles documentent `Idempotency-Key`. La clé doit protéger l'effet métier, pas seulement satisfaire une exigence de header.
Elle donne enfin un vocabulaire utile pour la reprise: effet irréversible, clé naturelle, journal d'exécution, concurrence, rejet contrôlé et compensation. Ces notions évitent de transformer un timeout en doublon financier.
Piloter relecture d'ordre, capture et incident Scalapay
La ressource webhook ou polling API aide à décider quand relire l'ordre Scalapay, quand attendre une preuve de capture ou de refund, et quand garder une commande en attente sans déclencher trop vite la suite métier.
Quand un ordre expire, qu'une capture reste ambiguë ou qu'un reporting Scalapay ne se rapproche plus, le runbook d'incident API donne la méthode pour isoler le lot, geler le bon segment et reprendre seulement les dossiers concernés.
Rapprocher Scalapay avec ERP et comptabilité
La ressource réconciliation API devient utile dès que reporting Scalapay, ERP, boutique et comptabilité racontent des états différents. Elle donne un cadre pour identifier la source qui doit trancher.
Elle complète la partie BNPL en donnant une méthode pour classer les écarts: capture absente, refund partiel mal ventilé, ordre expiré, avoir absent, référence perdue ou dossier invisible dans un portail.
Elle permet surtout de sortir du rapprochement artisanal. Les écarts sont qualifiés par période, montant, statut, référence et système propriétaire, ce qui rend la correction défendable auprès de la finance.
Préparer les écritures financières aval
La ressource facturation électronique API prolonge le sujet quand une capture Scalapay déclenche facture, avoir ou écriture comptable. Elle aide à cadrer les dépendances entre paiement, livraison et document financier.
Elle devient utile quand une commande BNPL ouvre une chaîne plus large: facture, remboursement, statut de paiement, contrôle TVA, reporting et synchronisation ERP. La capture ne doit pas créer une écriture si la preuve métier est incomplète.
Pour passer du cadrage à l'exécution, la landing API paiement donne le cadre général, tandis que la page intégrateur Scalapay précise l'accompagnement possible sur ce connecteur.
Conclusion: brancher Scalapay sans dette BNPL
Une intégration API Scalapay fiable commence par une chronologie respectée: commande créée, token conservé, checkout ouvert, ordre relu, capture exécutée, delay surveillé, refund rapproché et reporting exploité. Chaque étape porte une preuve différente.
Les détails qui font la différence ne sont pas décoratifs: `checkoutUrl`, `token`, `merchantReference`, `Idempotency-Key`, `orderExpiryMilliseconds`, `refundAmount`, `merchantRefundReference`, statuts d'ordre, statuts de capture et reporting.
Le vrai coût d'un mauvais connecteur Scalapay apparaît rarement pendant le premier test. Il apparaît quand une autorisation n'est pas capturée, quand un refund part sans avoir, ou quand une commande expirée continue de vivre côté boutique.
Si vous devez intégrer Scalapay 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 paiement fractionné sans dette cachée.
