Dans ce menu Point de vente, vous pouvez configurer les paramètres de l'intégration Exchange. Vous indiquez si vous souhaitez utiliser une URL Exchange dynamique ou statique, sélectionnez la méthode d'appel (comme TXT, XML, JSON), définissez un séparateur et choisissez un schéma de nouvelle tentative pour les appels échoués. Vous déterminez également quelles mises à jour de statut doivent être communiquées via l'Exchange, par exemple tous les statuts, uniquement les commandes payées ou uniquement les changements de statut de commande.
| Institution | Valeur |
|---|---|
| Configuration d'Exchange |
|
| URL d'échange | URL : https:// |
| Méthode d'appel |
|
| Séparateur |
|
| Système de retour |
|
| État de la communication |
|
Signed JSON POST est à privilégier
Le Signed JSON est à privilégier, car il contient toutes les données nécessaires. Aucun appel API supplémentaire n'est donc nécessaire. L'authenticité et l'intégrité des données peuvent être validées directement à l'aide des en-têtes fournis. Le whitelisting IP n'est pas non plus nécessaire dans ce cas.
Pour en savoir plus, consultez notre portail développeurs dans l'article Exchange Signing
Intervalles du schéma de nouvelle tentative
Le schéma de nouvelle tentative répète un appel Exchange échoué selon des intervalles prédéfinis jusqu'à ce que le serveur renvoie « TRUE ». Cela confirme que la requête a été traitée avec succès. L'utilisation de différents intervalles entre les tentatives permet d'éviter la surcharge du serveur et augmente les chances qu'un problème temporaire soit résolu avant que la requête ne soit retentée.
| Moment de réessai | 10 fois / 24 h (augmentation) | 11x / 24h (équilibré) | 8 fois par quart d'heure | 6x / 2h | 1x / 5s |
|---|---|---|---|---|---|
| 1ère tentative après : | 1 seconde | 10 secondes | 15 minutes | 30 secondes | 5 secondes |
| 2e tentative après : | 3 secondes | 30 secondes | 30 minutes | 50 secondes | - |
| 3ème tentative après : | 10 secondes | 1 minute | 45 minutes | 70 secondes | - |
| 4ème tentative après : | 30 secondes | 2 minutes | 60 minutes | 5 minutes | - |
| 5ème tentative après : | 60 secondes | 1 heure | 75 minutes | 30 minutes | - |
| 6ème tentative après : | 5 minutes | 3 heures | 90 minutes | 60 minutes | - |
| 7ème tentative après : | 30 minutes | 6 heures | 105 minutes | - | - |
| 8e tentative après : | 60 minutes | 10 heures | 120 minutes | - | - |
| 9e tentative après : | 12 heures | 14 heures | - | - | - |
| 10e tentative après : | 24 heures | 19 heures | - | - | - |
| 11e tentative après : | - | 24 heures | - | - | - |
Quand un exchange est-il réussi ?
Un appel Exchange est considéré comme réussi lorsque le serveur renvoie TRUE et que le code de statut HTTP est 200. Si l'une de ces deux conditions n'est pas remplie, l'appel Exchange est considéré comme échoué et le schéma de nouvelle tentative configuré s'applique.
Le schéma de nouvelle tentative répète un appel Exchange échoué selon des intervalles prédéfinis en cas d'échec. Cela confirme que la requête a été traitée avec succès. L'utilisation de différents intervalles entre les tentatives permet d'éviter la surcharge du serveur et augmente les chances qu'un problème temporaire soit résolu avant que la requête ne soit retentée.
Communication de statut
Avec la communication de statut, vous déterminez vous-même quels statuts de transaction sont transmis à l'URL Exchange. Vous ne recevez ainsi que les notifications pertinentes, évitez les notifications inutiles et pouvez piloter vos workflows plus efficacement.
| Taper | Action | Code | Tous | Paiement complet uniquement | Modification de commande | Modifications non en attente |
|---|---|---|---|---|---|---|
|
En attente |
en attente | 20 | ✔ | ✖ | ✖ | ✖ |
| en attente | 25 | ✔ | ✖ | ✖ | ✖ | |
| en attente | 50 | ✔ | ✖ | ✖ | ✖ | |
| en attente | 90 | ✔ | ✖ | ✖ | ✖ | |
| Modification de commande | nouveau_ppt | 100 | ✔ | ✔ | ✔ | ✔ |
| Annuler | -90 | ✔ | ✖ | ✔ | ✔ | |
| Annuler | -80 | ✔ | ✖ | ✔ | ✔ | |
| autoriser | 95 | ✔ | ✖ | ✔ | ✔ | |
| capturer | 100 | ✔ | ✔ | ✔ | ✔ | |
| remboursement | -72 | ✔ | ✖ | ✔ | ✔ | |
| remboursé | -81 | ✔ | ✔ | ✔ | ✔ | |
| refusé | -63 | ✔ | ✖ | ✔ | ✔ | |
| refusé | -64 | ✔ | ✖ | ✔ | ✔ | |
| échec | -60 | ✔ | ✖ | ✔ | ✔ | |
| vérifier | 85 | ✔ | ✖ | ✔ | ✔ | |
| remboursement | -71 | ✔ | ✖ | ✔ | ✔ | |
| annulation de remboursement | 100 | ✔ | ✔ | ✔ | ✔ | |
| Mutation (action) | remboursement : ajouter | -72 | ✔ | ✖ | ✔ | ✔ |
| remboursement : supprimer | 100 | ✔ | ✔ | ✔ | ✔ | |
| remboursement : reçu | -81 | ✔ | ✔ | ✔ | ✔ | |
| remboursement : annulation | 100 | ✔ | ✔ | ✔ | ✔ | |
| collection:ajouter | 50 | ✔ | ✖ | ✔ | ✖ | |
| collection | 100 | ✔ | ✔ | ✔ | ✔ | |
| collection:supprimée | ✔ | ✖ | ✔ | ✔ | ||
| annulation de prélèvement automatique | -63 | ✔ | ✖ | ✔ | ✔ |
Notification d'échec Exchange
Lorsque Pay. appelle votre URL Exchange après un changement de statut, une réponse est attendue pendant 5 secondes maximum. Il peut toutefois arriver que votre serveur ne réponde pas temporairement ou rencontre une panne.
Une fois les tentatives du schéma de nouvelle tentative terminées, nous envoyons alors une notification d'échec Exchange par e-mail à tous les utilisateurs marchands ayant activé cette notification par e-mail dans leur compte personnel.
L'appel Exchange échoue ou dure trop longtemps (> 5 secondes)
Lorsqu'un appel Exchange dure plus de 5 secondes, nous interrompons la connexion et considérons la requête comme échouée. Cela ne signifie toutefois pas automatiquement que le traitement sur votre serveur s'est également arrêté.
Il peut donc arriver que votre serveur n'ait pas traité un changement de statut, ou l'ait traité de manière incorrecte. Dans certains cas, le statut de la commande dans votre propre back-office peut alors différer du statut dans le Panneau d'administration de Pay.
Vérifiez l'access log
Vérifiez d'abord dans l'access log combien de temps l'appel Exchange a réellement duré. Cela vous permet de déterminer si le délai provient du réseau ou du traitement sur votre serveur. Dans la plupart des cas, le délai se situe dans le traitement lui-même.
Par exemple :
2026-08-19T10:17:32.481+02:00 INFO access exchange=payment-api method=POST path=/v1/paynl/exchange status=200 duration=7000ms remote_ip=10.20.30.40
Dans cet exemple, le traitement a duré 7000 ms (7 secondes) et a donc dépassé le temps de réponse maximal de 5 secondes.
Examinez le processus Exchange
S'il ressort de l'access log que le traitement prend trop de temps, examinez alors quels composants de votre backend en sont responsables. Une journalisation suffisante autour des différentes étapes du processus Exchange est importante à cet effet.
Les causes fréquentes d'appels Exchange lents sont :
- Requêtes de base de données lentes
- La génération de fichiers PDF ou d'e-mails
- Appels API externes lents
- Serveurs surchargés
- Un cold start d'un service
Attention : lorsque Pay coupe la connexion après 5 secondes, cela ne signifie pas que le processus sur votre serveur s'arrête automatiquement. Le backend peut quand même terminer le traitement. Tenez-en compte pour éviter un traitement en double ou incohérent.
Essayez, dans la mesure du possible, d'exécuter de manière asynchrone les tâches qui ne sont pas indispensables au traitement de l'appel Exchange. Renvoyez d'abord une réponse réussie le plus rapidement possible, puis effectuez par exemple la génération d'e-mails ou de PDF ensuite.
Autres solutions aux erreurs
Dans le journal des états de paiement (Payment state log), vous trouverez notamment le code HTTP correspondant. Si celui-ci n'a pas la valeur 200, une erreur s'est produite. Cette checklist en ligne vous permet de découvrir comment résoudre les problèmes les plus fréquents.
Recevez-vous actuellement une notification d'échec Exchange et souhaitez-vous la désactiver ? Demandez alors à votre administrateur PAY. de la désactiver dans le menu Admin Collaborateurs. Dans cet article, nous expliquons comment désactiver cet e-mail de notification.
Puis-je demander un délai d'expiration Exchange plus long ?
Oui, il est possible de demander un délai d'expiration plus long pour les appels Exchange. Nous ne le recommandons toutefois pas.
Le délai d'expiration standard est volontairement court. Un appel Exchange est destiné à traiter rapidement un changement de statut et à renvoyer une réponse. Lorsque votre endpoint Exchange dépasse régulièrement le délai d'expiration, il est donc préférable d'examiner d'abord pourquoi le traitement prend autant de temps.
Payment state log
Requêtes Exchange via le Payment state log
Requêtes Exchange via le Payment state log
Le Payment state log est un tableau contenant tous les appels exchange entre Pay. et le serveur de votre implémentation (boutique en ligne) des 35 derniers jours. Il n'est pas possible de consulter des appels exchange datant de plus de 35 jours.
Consulter les appels Exchange échoués
Suivez les étapes ci-dessous pour consulter les appels Exchange.
-
Allez sur My.pay.nl
-
Cliquez sur l'onglet Rapports puis sur l'onglet Payment state log.
-
Activez le filtre et choisissez par exemple le type de filtre Statut est égal à Échoué puis cliquez sur Récupérer les données.
-
Le rapport affiche maintenant tous les appels avec le statut échoué.
-
Cliquez sur une ligne du tableau ou sur l'icône Détails à droite de la ligne pour consulter un appel externe échoué
-
Cliquez sur Rappeler pour rappeler cet appel unique.
Rappeler plusieurs appels Exchange échoués à la fois
-
Allez sur My.pay.nl
-
Cliquez sur l'onglet Rapports puis sur l'onglet Payment state log.
-
Cliquez en haut à droite de l'aperçu (à côté de l'icône point d'interrogation) sur l'icône Configuration. Faites défiler vers le bas et réglez le champ Résultats par page sur le nombre souhaité d'appels Exchange (500 est la limite)
-
Activez le filtre et choisissez le type de filtre Statut est égal à Échoué puis cliquez sur Récupérer les données.
-
Le rapport affiche maintenant tous les appels avec le statut échoué. Cochez tous les appels dans l'en-tête du tableau
-
Cliquez en bas à gauche du Payment State Log sur le menu déroulant et choisissez Rappeler puis cliquez sur OK
-
Répétez cette opération jusqu'à ce que tous les appels échoués aient été traités