Search Overlay
Searchbox effacer les filtres de recherche ESC
Filter PreferencesClear

No results found

Pour commencer

Étape 1 : Obtenez vos identifiants API

Avant d'effectuer des appels API de serveur à serveur, vous avez besoin d'une clé API privée pour vous authentifier auprès de Paysafe.

Pour obtenir des clés d'API privées :

  1. Connectez-vous au portail commercial de Paysafe.

  2. Allez dans Développeur > Clés API.

  3. Sous Clé secrète, cliquez sur Authentifier maintenant.

  4. Saisissez le mot de passe de votre Business Portal et cliquez sur Confirmer.

  5. Vous verrez maintenant votre nom d'utilisateur et votre mot de passe.

La clé API est construite comme suit :

  1. Combinez le nom d'utilisateur et le mot de passe dans une chaîne séparée par deux points, par exemple, Nom d'utilisateur:Mot de passe.
  2. La chaîne littérale qui en résulte est ensuite encodée à l'aide de Base64.

Par exemple :

  • Nom d'utilisateur : MerchantXYZKey

  • Password: B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

La clé est formée par l'encodage base64.

MerchantXYZKey:B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

Clé API codée en base64: TWVyY2hbnRYWVpLXk6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZkNzAyMTUxMTgyZmRjOTUyMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=.

Ces informations d'identification sont requises pour toutes les demandes d'API. Manipulez-les en toute sécurité, traitez-les comme des mots de passe et ne les exposez jamais dans le code du frontend ou ne les partagez pas publiquement.

Étape 2 : Comprendre le payment handle et le traitement des transactions

Un Payment Handle est un jeton qui représente les détails du paiement et du profil du client. Il comprend des informations telles que

  • le numéro de la carte

  • Les modes de paiement alternatifs

  • l'adresse de facturation

  • le profil du client.

Fonctionnement

  1. Collecte frontale:
    • Collectez en toute sécurité les détails du paiement/profil à l'aide de vos champs hébergés.
  2. Tokenisation:
    • Les informations collectées sont envoyées à Paysafe, qui renvoie un paymentHandleToken.
  3. Traitement de la transaction:
    • Utilisez ce token pour terminer la transaction.

Les Payment Handles ne s'appliquent qu' aux paiements, aux versements et aux vérifications. Ils ne sont pas nécessaires pour d'autres types de transaction tels que le règlement, le remboursement ou l'annulation d'un paiement ou d'un règlement, etc.

Les étapes mentionnées ci-dessus s'appliquent à l'intégration serveur à serveur ou à l'intégration API pure.

  • Si vous utilisez Paysafe Checkout, les étapes 1 et 2 sont prises en charge par le système de paiement. Vous n'avez qu'à implémenter l'étape 3.

  • Si vous utilisez Paysafe.js ou le SDK Mobile, l'étape 2 est gérée par Paysafe.js ou le SDK. Vous devrez implémenter les étapes 1 et 3.

Vous devez créer un Payment Handle distinct pour chaque type de transaction. Par exemple, si votre intégration comprend à la fois un paiement et un versement, vous devrez générer deux Payment Handles distincts - un pour chaque transaction.

Types de Payment Handle

Paysafe propose deux types de Payment Handle :

1. le Payment Handle à usage unique.

  • Délai de mise en service: Généralement 15 minutes.
  • Utilisation: Utilisation unique.
  • Cas d'utilisation: Typique pour les transactions immédiates et uniques.

Ladurée de validité peut varier en fonction du mode de paiement. Vérifiez toujours le champ timeToLiveSeconds dans la réponse de l'API pour déterminer la durée de validité exacte.

2. le Payment Handle à usages multiples

  • Durée de vie: Illimité.

  • Utilisation: Peut être réutilisé pour plusieurs transactions.

  • Cas d'utilisation: Pour les Paiements récurrents.

  • Disponible pour les modes de paiement: Cartes, PaysafeCash, BACS, SEPA.

Des payment handles à usage multiple sont créés pour les cartes enregistrées, ce qui permet d'effectuer des transactions continues et répétées sans avoir à fournir les détails de la carte à chaque paiement.

Ce mécanisme s'applique également aux accords de prélèvement automatique, où les mandats sont liés aux payment handles à usage multiple, ce qui garantit un traitement sûr et efficace des Paiements récurrents.

Notez que des payment handles à usage multiple distincts sont créés pour les cartes enregistrées, les mandats de prélèvement et PaysafeCash. Ils sont générés et gérés indépendamment pour répondre aux exigences spécifiques de leur mode de paiement respectif.

Gestion du cycle de vie

Transitions d'état

En comprenant ces états et ces transitions, vous pouvez gérer efficacement le cycle de vie d'un Payment Handle et garantir à vos clients un processus de transaction fluide.

Payment Handle à usage unique

  • Les payment handles à usage unique passent par différents états tels que INITIATED, PAYABLE, COMPLETED, EXPIRED, FAILED et CANCELLED.
État Description de l'état Prochaines étapes

INITIATED

Le processus de paiement a commencé et le payment handle a été créé.

Le payment handle est prêt à être utilisé pour d'autres actions telles que REDIRECT.

PAYABLE

Le payment handle est prêt à recevoir une demande de paiement/versement.

Vous pouvez maintenant faire une demande de paiement ou de retrait en utilisant le jeton du payment handle. Ce statut est activé après une authentification ou une redirection réussie.

COMPLETED

Le payment handle a été utilisé avec succès dans le cadre d'un paiement ou d'un retrait.

Aucune autre action n'est requise. La transaction est terminée.

EXPIRED

Le payment handle n'est plus valide.

Un nouveau payment handle doit être créé pour relancer le processus.

FAILED

Le processus de transaction a rencontré une erreur.

Recherchez la cause de l'échec et relancez éventuellement le processus avec un nouveau payment handle.

CANCELLED

 Le processus de transaction a été annulé par l'utilisateur ou le système. Le cas échéant, relancez le processus avec un nouveau payment handle.
ERROR Le payment handle n'a pas pu être créé et a provoqué une erreur. Un nouveau payment handle doit être créé pour relancer le processus.

Multi-usagePayment Handle

Statut Description de l'erreur Prochaines étapes

PAYABLE

 Le Payment Handle est prêt pour une transaction ou une demande de paiement initiée par le commerçant. Ce statut s'applique aux Cartes et à PaysafeCash.

EXPIRED

 Le payment handle n'est plus valide. Ce statut ne s'applique qu'au payment handle multi-usage PaysafeCash.

Webhooks et appels GET

  • Webhooks: Ils informent votre système des changements de statut du payment handle.

Il est recommandé de surveiller les Webhooks pour obtenir des mises à jour en temps réel sur l'état du payment handle, en particulier pour les paiements asynchrones dont le traitement est retardé.

  • Appels GET: Vous pouvez également obtenir le statut du payment handle à l'aide d'appels GET, mais il est recommandé d'utiliser des Webhooks pour les mises à jour en temps réel plutôt que de procéder à une interrogation à l'aide d'appels GET.

Il est recommandé d'utiliser un seul appel GET pour reconfirmer l'état reçu dans les webhooks, ce qui permet de s'assurer que les paquets de webhooks n'ont pas été altérés. Bien qu'il ne soit pas recommandé d'utiliser les appels GET pour une interrogation continue, si vous ne recevez pas le webhook dans le délai imparti, vous pouvez toujours utiliser un appel GET pour obtenir le dernier état.

Domaines importants

La réponse Payment Handle comprend des attributs importants qui guident le processus de paiement. Vous trouverez ci-dessous certains attributs qui sont essentiels pour comprendre comment procéder au paiement et s'assurer que l'intégration gère correctement le processus de paiement.

Actions

Spécifie les actions supplémentaires que vous pouvez entreprendre pour compléter une demande de paiement. Il s'agit d'un paramètre en lecture seule renvoyé par Paysafe dans la réponse de la demande de création de Payment Handle, quel que soit le mode de paiement sélectionné par le client.

  • AUCUN: Vous pouvez immédiatement effectuer un appel de paiement car le jeton du Payment Handle est défini sur PAYABLE immédiatement.
  • REDIRECT: Le client doit autoriser le paiement sur une page redirigée, généralement pour les transactions 3D Secure. Vous devez rediriger votre client vers un lien renvoyé par Paysafe dans la réponse. Une fois l'authentification réussie, le statut du jeton Payment Handle est défini sur PAYABLE. Vous devez effectuer une demande de paiement à l'aide du jeton de Payment Handle immédiatement après qu'il est devenu PAYABLE. La durée de validité du jeton est de 15 minutes.

Types de tokens

  • SINGLE_USE: Le jeton de Payment Handle ne peut être utilisé qu'une seule fois.
  • MULTI_USE: Le handle token de paiement peut être utilisé plusieurs fois, ce qui convient aux transactions récurrentes telles que les abonnements ou les cartes enregistrées.

Modes d'exécution

Paiements : Indique si la demande de paiement sera exécutée immédiatement ou avec un certain retard. Il s'agit d'un paramètre en lecture seule renvoyé par Paysafe dans la réponse à la demande de création d'un payment handle.

  • SYNCHRONOUS(synchrone) : reçoit l'état du paiement de manière synchrone. Vous pouvez interroger les Paiements en cours/en attente à intervalles réguliers pour connaître l'état des paiements.
  • ASYNCHRONIQUE: reçoit l'état du paiement de manière asynchrone. Le paiement est censé être effectué après un délai important, qui peut s'étendre sur des heures ou des jours (par exemple, PaysafeCash). Vous pouvez utiliser des Webhooks pour recevoir le statut du paiement instantanément dans de tels cas.

Traitement des transactions

Vous pouvez traiter différents types de transactions tels que les paiements, les versements, les règlements, les remboursements, les annulations de paiement, etc. à l'aide d'API.

Les payment handles ne s'appliquent qu' au paiement, au versement et à la vérification. Ils ne sont pas nécessaires pour d'autres types de transaction tels que le règlement, le remboursement ou l'annulation d'un paiement ou d'un règlement, etc.

 

Étape 3 : Comprendre les environnements

Paysafe prend en charge deux environnements distincts pour l'intégration de l'API :

  • Environnement de test: Utilisé pour le développement et les tests. Les transactions sont simulées et n'impliquent pas de fonds réels.

  • Environnement de production: Utilisé pour traiter des transactions en direct dans un environnement réel.

Assurez-vous que vous utilisez l'environnement et les informations d'identification appropriés en fonction de votre stade de développement ou de déploiement.

Étape 4 : Effectuer des appels à l'API

Avant de lancer votre premier appel à l'API, vous devez disposer d'une partie ou de la totalité des informations suivantes :

  • Point de terminaison d'API: Il s'agit de l'URL à laquelle vous envoyez votre demande, et son format dépend du type d'appel 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 HTTPS d'autorisation de la plupart des demandes 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 et contenir des objets JSON Paysafe valides, comme requis pour le type de demande. Tous les appels API ne nécessitent pas un corps de message. Par exemple, les demandes GET ne nécessitent pas de corps de message.
  • ID de la ressource: Certains appels API nécessitent un ID de la 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 lors de l'une des étapes précédentes.

Exemple

L'extrait de code ci-dessous fournit un exemple des informations d'identification ci-dessus, incluses dans une requête cURL :

curl -X POST https://api.test.paysafe.com/paymenthub/v1/payments \N-u 1001062690:B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7 \N-H 'Content-Type : application/json'

Utilisez le format de requête de l'API comme indiqué dans l'exemple ci-dessus :

  • 1001062690 - La séquence de chiffres avant les deux points est votre nom d'utilisateur, à inclure dans le point de terminaison d'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 encodés en Base64 avant d'être inclus dans votre demande d'API. Vous pouvez le faire manuellement ou utiliser un outil pour automatiser cette opération.

Étape 5 : Tests

L'environnement de test Paysafe vous permet de tester votre site Web ou votre application sans initier de transactions réelles via la plateforme en direct (production). Les transactions dans cet environnement sont traitées à l'aide d'un simulateur, qui renvoie une réponse réussie (approuvée) ou échouée (refusée) en fonction des paramètres soumis dans la demande API.

En utilisant les comptes de test de l'API Paiements Paysafe, vous pouvez :

  • Vérifier la prise en charge de tous les types d'opérations requis.

  • Examiner les erreurs courantes ainsi que celles spécifiques à chaque opération.

  • Confirmer la longueur et le format de tous les attributs soumis.

  • Vous assurer de l'utilisation correcte des méthodes HTTP (la plupart des requêtes API utilisent POST, tandis que GET est utilisé pour récupérer des informations).

Pour demander l'accès au compte de test et les informations d'identification, contactez votre Business Relationship Manager ou envoyez un courriel à integrations@paysafe.com. Les comptes de test donnent également accès au Paysafe Business Portal - version test, où vous pouvez suivre et examiner vos transactions de test.

  • Point de terminaison de l'API d'essai: https://api.test.paysafe.com/paymenthub/v1

Étape 6 : Commencer à accepter les paiements

L'environnement de test reflète les fonctionnalités de l'environnement de production, ce qui vous permet de valider entièrement votre intégration avant de la mettre en œuvre. Une fois les tests terminés, reproduisez les mêmes changements de configuration dans votre compte de production.

Pour vous connecter à l'environnement de production Paysafe, utilisez les détails suivants :

  • Point de terminaison de l'API de l'environnement de production: https://api.paysafe.com/paymenthub/v1

  • Authentification: Les clés API seront fournies dans votre portail commercial Paysafe.

Les identifiants de test ne peuvent pas être utilisés dans l'environnement de production. Veillez à mettre à jour votre intégration avec des informations d'identification spécifiques à la production avant de traiter des transactions en direct.

Sur cette page