Pour commencer
L’API de paiement vous permet de traiter facilement et en toute sécurité les paiements de vos clients à l’aide d’une seule API – l’API de paiements. Connectez votre application directement à l’API de paiement pour traiter une gamme complète de modes de paiement basés sur REST.
Pour commencer à utiliser les API de paiement, procédez comme suit :
- Obtenez votre clé API
- Familiarisez-vous avec les "payment handles"
- Testez dans notre bac à sable
- Mise en service
Obtenir vos clés API
- Paysafe vous fournira les authentifiants dans le portail d’entreprise.
- Ouvrez une session dans le portail d’entreprise.
- Pour accéder à vos clés, dans la barre de navigation de gauche, cliquez sur Intégrer > Clés API. Vous trouverez une nouvelle section qui affiche la clé de l’API de paiement Paysafe que vous devez utiliser : La clé privée : est utilisée pour toutes les requêtes API de serveur à serveur https://api.test.paysafe.com/paymenthub/v1
Passer des appels API
Avant de lancer votre premier appel à l’API, vous devrez disposer de tout ou partie des informations suivantes :
- Point de terminaison API : il s’agit de l’URL à laquelle vous envoyez votre requête, et son format dépend du type d’appel à l’API.
- Clé API : vous obtenez vos clés API lorsque vous vous inscrivez auprès de Paysafe. Vous devez l’inclure dans l’en-tête d’autorisation HTTPS de la plupart des requêtes d’API. Reportez-vous à la section ci-dessus (Obtenir vos clés API) pour plus d’informations.
- Corps du message : il doit s’agir d’un JSON valide qui contient des objets JSON Paysafe valides, conformément au type de requête. Tous les appels d’API ne nécessitent pas un corps de message. Par exemple, les requêtes GET ne nécessitent pas de corps de message.
- Identifiant de ressource : certains appels d’API nécessitent un identifiant de ressource dans le point de terminaison API. Par exemple, vous pouvez avoir besoin de cet identifiant pour faire référence à une ressource créée dans l’une des étapes précédentes.
Exemple
Le bout de code ci-dessous donne un exemple des authentifiants ci-dessus, incluses dans une requête cURL :
curl -X POST https://api.test.paysafe.com/paymenthub/v1/payments \
-u 66040-1001062690:B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7 \
-H ’Content-Type: application/json’
Utilisez le format de requête API comme indiqué dans l’exemple ci-dessus :
- 66040-1001062690 – la séquence de chiffres avant les deux points est votre nom d’utilisateur, à inclure dans le point de terminaison API.
- B-qa2-0-579b6aec-0-… – la séquence de chiffres après les deux points est votre mot de passe.
- Le nom d’utilisateur et le mot de passe doivent être codés en Base64 avant d’être inclus dans votre requête API. Vous pouvez le faire manuellement ou utiliser un outil pour l’automatiser. Pour plus d’informations, voir Authentification.
Dépannage des requêtes API
Vous trouverez ci-dessous une brève liste de questions susceptibles d’entraîner des problèmes.
- La requête n’est pas envoyée via HTTPS
- Les bons détails d’authentification (c’est-à-dire votre clé API) n’ont pas été inclus – une erreur fréquente consiste à ajouter des espaces avant ou après la clé API.
- Syntaxe JSON incorrecte dans le corps de votre requête
- Spécification d’une méthode HTTP incorrecte – pour la plupart des requêtes API, il s’agit de la méthode POST, alors que les requêtes visant à récupérer des informations de la plateforme Paysafe utilisent la méthode GET.
Pour plus de détails, voir la rubrique Dépannage.
Aperçu d’un "payment handle"
Un "payment handle" représente les détails de l’instrument de paiement et le profil d’un client. Le "payment handle" comprend des informations comme le numéro de la carte de crédit, la date d’expiration, le nom du titulaire de la carte, le type de transaction, l’adresse de facturation et des informations sur le profil du client.
Lorsque vous créez un "payment handle", Paysafe renvoie un jeton paymentHandleToken dans la réponse. Ce jeton comporte tous les détails de paiement d’un client que vous devez inclure dans une requête de paiement. Vous devez créer un "payment handle" distinct pour chaque type de transaction. Par exemple, si votre transaction comporte une requête de paiement et un crédit autonome, vous devrez créer des "payment handles" distincts pour le paiement et le crédit autonome.
Les "payment handles" ont une durée de 15 minutes et ne peuvent être utilisés qu’une seule fois. Toutefois, dans certains cas, par exemple lorsque vous créez un "payment handle" pour un client, ce dernier être utilisé plusieurs fois et avoir une durée illimitée.
Indique les actions supplémentaires que vous pouvez entreprendre pour compléter une demande de paiement. Ce paramètre est en lecture seule. Paysafe le renvoie dans la réponse à la demande de création du "payment handle", quelle que soit le mode de paiement choisi par le client.
Les valeurs éventuelles sont :
- NONE : dans ce cas, vous pouvez immédiatement effectuer un appel de paiement, car le jeton de "payment handle" est réglé sur PAYABLE immédiatement.
- REDIRECT : le client doit autoriser le paiement sur une page redirigée. C’est généralement le cas pour les transactions 3D Secure, car elles sont redirigées vers la page 3D Secure du fournisseur de la carte pour l’authenfification de la transaction. Vous devez rediriger votre client vers un lien renvoyé par Paysafe dans la réponse. Une fois l’authentification réussie, l’état du jeton de paiement est réglé sur PAYABLE.
Vous devez effectuer une requête de paiement à l’aide du jeton de paiement immédiatement après que l’état du jeton est devenu PAYABLE. Le jeton est valide pendant 15 minutes.
Indique si vous pouvez utiliser le jeton PaymentHandleToken une ou plusieurs fois. Ce paramètre est en lecture seule. Paysafe le renvoie dans la réponse à la requête de création d’un "payment handle".
Les jetons de "payment handle" sont de deux types : SINGLE_USE (jeton de paiement ordinaire) et MULTI_USE (jeton de paiement d’un client).
- SINGLE_USE : le jeton de paiement ne peut être utilisé qu’une seule fois.
- MULTI_USE : le jeton de paiement peut être utilisé plusieurs fois. Il peut être utilisé pour des transactions récurrentes comme des abonnements ou des cartes de crédit enregistrées.
Indique si la requête de paiement sera exécutée immédiatement ou avec un certain retard. Ce paramètre est en lecture seule. Paysafe renvoie ces informations dans la réponse à la demande de création d’un "payment handle". Vous pouvez utiliser ces informations pour déterminer si vous souhaitez recevoir l’état du paiement de manière synchrone ou si vous souhaitez vous appuyer sur des liens derappel HTTP.
Les valeurs éventuelles sont :
- SYNCHRONOUS : recevoir l’état des paiements de manière synchrone. Vous pouvez interroger les paiements en cours de traitement/en attente à intervalles réguliers pour connaître l’état du paiement.
- ASYNCHRONOUS : recevoir l’état des paiements de manière asynchrone. Le paiement devrait être effectué après un retard important. Par exemple, le retard peut durer des heures ou des jours (comme dans le cas de PaysafeCash). Vous pouvez utiliser les liens de rappel HTTP pour recevoir instantanément l’état du paiement dans de tels cas.
Test d’API
Vous pouvez utiliser l’environnement de test Paysafe pour tester des sites Web ou des applications sans effectuer de transactions via la plateforme de traitement Production (en temps réel). Les opérations de paiement traitées dans l’environnement de test sont exécutées sur un simulateur. En fonction des informations fournies dans la requête de transaction, le simulateur renvoie une réponse positive (approuvée) ou négative (refusée).
Les comptes de test de l’API de paiement Paysafe, vous permettent de faire ce qui suit :
- Vérifier la prise en charge de tous les types d’opérations dont vous avez besoin.
- Passer en revue toutes les erreurs courantes ainsi que les erreurs susceptibles de se produire pour chaque opération.
- Vérifier la longueur et le format de tous les attributs que vous envoyez.
- Spécification d’une méthode HTTP incorrecte – pour la plupart des requêtes API, il s’agit de la méthode POST, alors que les requêtes visant à récupérer des informations de la plateforme Paysafe utilisent la méthode GET.
Pour accéder aux comptes de test et aux authentifiants, veuillez contacter votre responsable des relations avec les entreprises ou vous adresser à integrations@paysafe.com. Votre compte de test vous donnera accès à une version test du portail d’entreprise Paysafe, où vous pourrez consulter l’état de vos transactions de test.
Point de terminaison API :https://api.test.paysafe.com/paymenthub/v1
Mise en service
Les comptes de test vous permettent de traiter des transactions API qui reflètent les fonctionnalités de l’environnement de production. Une fois que vous êtes satisfait de votre intégration à l’environnement de test, vous devez répéter les changements de configuration apportés à votre compte de test sur votre compte de production.
Vous devez utiliser les détails suivants pour vous connecter à chaque environnement de production Paysafe.
- Point de terminaison API :https://api.test.paysafe.com/paymenthub/v1
- Authentifiants : Paysafe vous fournira les clés API dans le portail d’entreprise.
- Vous ne pouvez pas utiliser vos identifiants de test pour traiter des demandes de transaction dans l’environnement de production.