Andorpay
Retour au blog

Publié le · Mis à jour le

SDK de paiement : API, intégration et tests

Distinguez le rôle du SDK de celui de votre serveur. Préparez commandes, webhooks et tests pour connecter votre application à AndorPay.

Des modules d’intégration relient un ordinateur à une carte de paiement.

Un SDK peut simplifier la connexion à un terminal de paiement virtuel, ou TPV. Mais l'intégration est complète lorsque le paiement est relié à la commande et déclenche la bonne action dans votre application. Commencez donc par identifier ce que vous souhaitez connecter : le traitement bancaire, une page de paiement hébergée ou le système qui organise vos encaissements.

Si vous développez un site ou un service pour une entreprise en Andorre, ce guide vous aide à distinguer le travail de la bibliothèque de celui de votre application. Avec AndorPay, vous pouvez préparer une connexion par API et utiliser les événements de paiement pour poursuivre la vente.

SDK, API et extension : trois rôles différents

Une API définit la communication entre deux systèmes. Un SDK rassemble des outils pour utiliser un service dans un langage ou un environnement donné. Une extension, ou plugin, relie ce service à une plateforme telle qu'une boutique et intègre généralement des choix de fonctionnement.

Ces outils ne sont pas interchangeables. Une application sur mesure peut appeler une API à travers un SDK. Une boutique peut installer une extension qui effectue ces appels en interne. Le commerçant doit comprendre le parcours final ; l'équipe technique doit choisir une connexion qu'elle pourra maintenir.

Les bibliothèques officielles de Redsys facilitent la préparation des paramètres, des requêtes et de leur signature. Votre application reste chargée de relier l'opération à l'achat et de mettre à jour son état.

Partir du besoin de votre application

Si vous utilisez déjà WooCommerce, examinez d'abord l'intégration disponible pour votre installation. Développer une nouvelle connexion peut ajouter un travail déjà pris en charge par l'extension. Notre guide WooCommerce décrit le lien entre paiement et commande avec AndorPay.

Pour une application sur mesure, identifiez le système qui crée l'achat, le serveur qui conserve sa référence et l'événement autorisant la livraison. Ces informations permettent de choisir où utiliser une bibliothèque. La rapidité d'installation d'un paquet ne suffit pas à résoudre les échanges entre vos outils.

Définir le service que vous allez intégrer

Une connexion directe à un processeur et l'intégration d'une plateforme de gestion des encaissements impliquent des responsabilités différentes. Dessinez d'abord les éléments du parcours : application, serveur, page de paiement, confirmation et système de livraison du service.

Avec AndorPay, votre serveur peut créer une session et diriger l'acheteur vers l'adresse renvoyée. L'application reçoit ensuite les notifications nécessaires pour poursuivre. Notre guide REST décrit ce contrat, sans supposer l'existence d'un SDK officiel pour chaque langage.

Clarifiez ce point avant de mélanger des exemples techniques. Une clé, une signature ou un champ Redsys n'a pas nécessairement le même format ni le même rôle dans une requête AndorPay. À chaque étape, utilisez la documentation du service réellement appelé.

Le travail qu'une bibliothèque peut vous éviter

Une bibliothèque adaptée au contrat réduit le code de communication à répéter et facilite l'emploi des formats attendus. Elle peut aussi rendre la connexion plus lisible : l'équipe sait où la requête est construite et où sa réponse est interprétée.

Cet intérêt apparaît notamment pendant la maintenance. Si le format d'un service change, vous devez pouvoir localiser le code concerné et vérifier sa mise à jour. Regroupez la connexion dans un module et traduisez ses résultats vers les états utilisés par votre activité.

L'écran d'une commande n'a pas besoin de connaître tous les paramètres bancaires. Il peut afficher une attente de confirmation, un paiement terminé ou une action nécessaire. Les détails techniques restent disponibles pour le diagnostic dans le composant chargé de la connexion.

Les responsabilités qui restent sur votre serveur

Le serveur relie l'achat au client, au produit et aux conditions correspondantes. Il contrôle également les données reçues du navigateur. L'acheteur peut sélectionner une option, mais l'application doit vérifier qu'elle correspond à une offre valable.

Dans l'intégration REST d'AndorPay, la clé d'API est un secret conservé côté serveur. Elle n'apparaît pas dans le JavaScript public et n'est pas renvoyée à l'acheteur. Le navigateur reçoit uniquement les informations nécessaires pour continuer, comme l'adresse de paiement fournie par le service.

Responsabilité Question à résoudre dans votre application
Achat Quel service est commandé et avec quelle référence ?
Client À quel compte appartient l'opération ?
Requête Quel service et quel environnement reçoivent les données ?
Confirmation Comment vérifier le résultat reçu ?
Livraison Quelle action correspond à ce paiement ?
Suivi Où consulter une opération en attente ?

Vérifiez aussi les droits de la personne qui déclenche chaque action. Une requête au bon format ne prouve pas qu'elle doit être exécutée pour n'importe quel utilisateur ou commande. Cette responsabilité reste dans l'application, même si une bibliothèque prépare la requête.

Une réponse technique ne termine pas la vente

Créer une session ouvre un parcours de paiement. Cela ne confirme pas que le client l'a terminé. De même, une adresse de retour permet de revenir sur votre site, mais elle ne doit pas être votre seule preuve pour marquer une commande comme payée.

Le client peut fermer la fenêtre après avoir autorisé l'opération, perdre sa connexion ou revenir avant la mise à jour du résultat. Votre système doit pouvoir recevoir la confirmation et l'associer à l'achat indépendamment de cette page.

La documentation du cycle de paiement explique cette distinction. Utilisez-la pour définir les états visibles dans l'application et éviter qu'un problème de navigation entraîne une nouvelle tentative de débit.

Préparer les notifications dès le départ

Les webhooks permettent au serveur de recevoir des événements sur les opérations. Vérifiez chaque message selon le contrat documenté avant d'en appliquer le contenu. Conservez le lien entre événement, transaction et commande afin de retrouver l'effet produit.

Une notification reçue plusieurs fois doit être reconnue. Si le premier message a ouvert une période de service, le suivant ne doit pas prolonger l'accès une nouvelle fois. L'application doit conserver les effets déjà appliqués, même lorsque le service renvoie le message.

Consultez notre guide des webhooks. Séparez la vérification du message de l'action commerciale qui suit. Vous pourrez ainsi examiner un problème de livraison du service sans demander un paiement déjà confirmé.

Vérifier les règles avant d'automatiser les nouvelles tentatives

Les services n'appliquent pas tous les mêmes règles aux requêtes répétées. Un conseil général sur l'idempotence ne remplace pas la documentation d'une opération. Vérifiez les en-têtes acceptés et les conséquences d'un nouvel envoi.

Notre guide REST précise notamment que POST /v1/checkouts refuse l'en-tête Idempotency-Key. Ne reprenez pas un exemple d'un autre prestataire qui l'ajoute systématiquement. Si le résultat reste incertain, conservez la référence disponible et vérifiez l'état avant de déclencher une nouvelle action de paiement.

Il faut également distinguer une nouvelle consultation, une nouvelle session et un débit. Ces actions n'ont pas les mêmes conséquences. Le traitement d'une erreur doit correspondre à l'opération concernée, plutôt qu'à une règle répétant toute requête ayant échoué.

Évaluer une dépendance avant de l'ajouter

Vérifiez qui publie le paquet et quelle documentation en décrit le périmètre. Examinez les langages et versions compatibles, le type d'intégration et la procédure de mise à jour. Un nom proche de celui du fournisseur ne prouve pas qu'il s'agit d'un outil officiel.

Préparez un test limité dans le bon environnement et notez la version utilisée. Il doit montrer que vous savez construire une requête valable, interpréter sa réponse et traiter une erreur connue. Reliez ensuite ce résultat à un achat de test dans votre application.

N'ajoutez pas une dépendance uniquement pour masquer un appel simple. Si vos outils actuels permettent une connexion claire à l'API, prenez en compte le travail de maintenance supplémentaire. L'objectif est une intégration compréhensible pour la personne qui devra résoudre un incident plus tard.

Tester le parcours complet

Vérifiez un paiement accepté, un refus et un abandon. Ajoutez une notification répétée et une confirmation arrivant après la fermeture du navigateur. Dans chaque cas, comparez le résultat de paiement avec l'état de la commande ou de l'accès au service.

Utilisez les identifiants et moyens de test de l'environnement prévu. Ne mélangez pas des paramètres de production pour faire fonctionner une démonstration. Notre guide de test décrit les scénarios et les limites des différents moyens de paiement.

Avant le lancement, précisez qui traite les incidents et quelles références sont nécessaires. Un test utile doit aussi permettre d'expliquer un échec sans rechercher des clés ou des données complètes de carte dans les journaux. Le diagnostic repose sur le contexte de l'opération.

Questions fréquentes

Un SDK supprime-t-il tout le travail d'intégration ?

Il peut simplifier la communication, mais votre application doit encore relier le paiement à l'achat, vérifier les événements et appliquer leur résultat. Le périmètre exact dépend de l'outil retenu.

Faut-il un SDK AndorPay pour mon langage ?

Vous pouvez connecter un serveur avec l'API REST documentée. Examinez le contrat et les fonctions nécessaires avant de choisir une dépendance. Pour une boutique compatible, commencez par étudier l'extension disponible.

Que faut-il fournir pour étudier mon projet ?

La plateforme, le langage du serveur, la banque et un schéma du parcours d'achat. Indiquez si vous vendez des produits, des prestations ou des abonnements et ce qui doit se passer après le paiement. Présentez-nous votre projet d'intégration pour préparer la connexion adaptée.

WhatsApp