Introduction

Sips est une solution de paiement de commerce électronique multicanale sécurisée conforme à la norme PCI DSS. Elle vous permet d’accepter et de gérer des transactions de paiement en prenant en compte les règles métier liées à votre activité (paiement à la livraison, paiement différé, paiement récurrent, paiement en plusieurs fois …).

L’objectif du présent document est d’expliquer l'intégration du moyen de paiement PayPal dans Sips .

A qui s’adresse ce document ?

Ce document a pour objectif de vous aider à implémenter le moyen de paiement PayPal sur votre site de commerce électronique.

Il comprend :

  • des informations fonctionnelles à votre attention ;
  • des instructions d'implémentation à destination de votre équipe technique.

Pour avoir une vue d’ensemble de la solution Sips , nous vous conseillons de consulter les documents suivants :

  • Présentation fonctionnelle ;
  • Guide de Configuration des fonctionnalités.

Contacter l'assistance

Pour toute question technique ou demande d'assistance, nos services sont disponibles :

  • par téléphone au : +33 (0) 811 10 70 33 ;
  • par e-mail : sips@worldline.com.

Pour faciliter le traitement de vos demandes, veuillez communiquer votre identifiant de commerçant : merchantId (numéro à 15 chiffres).

Comprendre les paiements PayPal avec Sips

Principes généraux

PayPal est un moyen de paiement en ligne exploité dans plus de 200 pays.

Pour payer avec PayPal, le client doit posséder un compte PayPal avec des moyens de paiement enregistrés. Pendant le paiement, après avoir sélectionné PayPal, le client doit s'identifier et choisir l'un des moyens de paiement enregistrés sur son compte. S’il n'a pas de compte PayPal, il peut en créer un au cours de la cinématique de paiement.

Règles d’acceptation

Fonctionnalités disponibles

Canaux de paiement
Internet V Canal de paiement par défaut
MOTO X
Fax X
SVI X
Typologies de paiement
Paiement immédiat V
Paiement en fin de journée V
Paiement différé V 29 jours maximum
Paiement à l'expédition V
Paiement en plusieurs fois X
Paiement par abonnement X
Paiement OneClick V
Gestion des devises
Acceptation multidevise V
Règlement en devise V

Demande d'autorisation

La durée d'autorisation maximale pour une transaction PayPal est de 29 jours. Après ce délai, la transaction est expirée.

Vérification de paiement

La vérification de paiement est une fonctionnalité de PayPal. Elle identifie les transactions à risque et vous informe afin de mettre en attente les expéditions jusqu'à ce que PayPal ait évalué le risque de la transaction.

Si un paiement est en cours de vérification par PayPal, l'état de la transaction est :

  • TO_CONFIRM_AUTHOR (vérification du paiement à l'étape d'autorisation) ;
  • TO_CONFIRM_CAPTURE (vérification du paiement à l’étape de la remise).

Un traitement par fichier est exécuté quotidiennement pour mettre à jour ces transactions vers des états finaux :

  • REFUSED (si le paiement a été refusé) ;
  • TO_CAPTURE/TO_VALIDATE (si l'autorisation a été approuvée) ;
  • CAPTURED (si la remise a été effectuée).

Le diagramme du paragraphe Effectuer un paiement PayPal schématise ces états ainsi que les transitions.

Le statut final apparaîtra dans vos journaux des transactions pour vous permettre de continuer le traitement de la commande.

Note: Les opérations de gestion de caisse ne sont pas disponibles pour les transactions dont l'état est TO_CONFIRM_AUTHOR ou TO_CONFIRM_CAPTURE .

Détails du panier d'achat

Sips permet d'envoyer à PayPal des informations sur le panier d'achat.

PayPal valide les montants en appliquant les règles suivantes :

  • Amount=ShoppingCart.TotalAmount+ShoppingCart.TotalTaxAmount+Delivery.ChargeAmount ;
  • ShoppingCartDetail.TotalAmount = ∑items item.UnitAmount∗item.Quantity ;
  • ShoppingCartDetail.TotalTaxAmount = ∑items item.UnitTaxAmount∗item.Quantity.

Si la validation d'une des trois règles échoue, le paiement est abandonné par PayPal. Le code réponse Sips et le code réponse acquéreur auront comme valeur « 12 » (Invalid Request).  

Gestion de l'adresse de livraison

PayPal affiche l'adresse de livraison sur ses pages de paiement. L'adresse de livraison peut être récupérée à partir de deux sources différentes :

  • depuis le compte PayPal du client ;
  • depuis les requêtes de paiement que vous transmettez à Sips .

La sélection est effectuée par le biais du champ paymentMeanData.paypal.addrOverride :

  • la valeur NO_OVERRIDE sélectionne l'adresse de livraison spécifiée dans le compte PayPal du client ;
  • la valeur OVERRIDE sélectionne l'adresse de livraison spécifiée dans la requête de paiement. Si aucune adresse n’est fournie dans la requête alors l’adresse du compte est affichée (valeur par défaut) ;
  • la valeur NO_DISPLAY n'affiche pas l'adresse de livraison.
Note: Lorsque la surcharge de l’adresse de livraison est choisie (valeur OVERRIDE ) et que l’adresse de livraison n’est pas conforme aux validations effectuées par PayPal, une erreur est retournée. Dans ce cas, afin d’éviter le blocage du paiement et l’affichage d’une page d’erreur, Sips désactive la surcharge de l’adresse de livraison (l’adresse utilisée sera alors celle associée au compte PayPal du client).

Créer votre compte PayPal

Afin d'utiliser le moyen de paiement PayPal sur votre site Web, vous devez posséder un compte PayPal. Il doit s'agir d'un compte professionnel (le type du compte est choisi lorsque vous vous enregistrez sur http://www.PayPal.com ).

Si vous avez plusieurs boutiques actives, nous vous suggérons de créer un compte PayPal pour chacune.

Paramétrer son compte PayPal

Sur votre compte PayPal, vous devez, en tant que commerçant, autoriser le prestataire de services de paiement (PSP) à appeler l'API de PayPal.

Note: Les captures des pages PayPal sont données ici à titre indicatif. Il se peut que PayPal modifie ses pages.

Dans votre compte PayPal entreprise, allez dans Préférences , Mes ventes puis Accès à l'API :

Cliquez sur le lien Ajouter ou modifier des droits d'accès API.

La fenêtre Ajouter de nouveaux droits d'accès à un tiers s'ouvre. Dans le champ textuel, entrez le compte technique Sips dlfr-sipspaypal_api1.atosorigin.com puis cliquez sur Rechercher .

Sélectionnez les options suivantes :

  • Utiliser PayPal Option+ pour traiter vos paiements ;
  • Effectuer un remboursement pour une transaction spécifique ;
  • Autoriser et collecter vos transactions PayPal .

Cliquez ensuite sur le bouton Ajouter .

Ajouter le compte PayPal sur Sips

Une fois que votre compte PayPal est créé, vous pouvez contacter l’assistance technique pour lui demander d’associer ce compte à votre boutique Sips . La seule information nécessaire est l’adresse électronique dont vous vous êtes servi pour créer votre compte PayPal.

Activer le paiement OneClick (optionnel)

Si vous le souhaitez, Sips vous permet d’accepter des paiements OneClick avec PayPal. Il faut pour cela :

  • avoir obtenu l’autorisation de PayPal de pouvoir dupliquer ses transactions ;
  • avoir souscrit au service Sips OneClick PayPal (contacter l’assistance technique) ;

Vous devrez ensuite transmettre un identifiant de wallet (champ merchantWalletId ) unique par client lors de vos demandes de paiement.

Inclure les transactions PayPal dans les journaux de rapprochement des impayés (optionnel)

Pour inclure les transactions PayPal dans les journaux de rapprochement des impayés générés par Sips , vous devez cocher l'option suivante dans votre compte PayPal :

Note: La génération de ces journaux n'est pas activée par défaut sur Sips . Contactez l'assistance pour l'activer si besoin.

Effectuer un paiement PayPal

Sips vous offre deux solutions pour intégrer le moyen de paiement PayPal :

  • Sips Paypage qui assure l’interface de paiement directement avec le client via son navigateur Web.
  • Sips Office qui vous laisse la possibilité d’afficher vous-même vos pages de paiement et qui fonctionne par un dialogue de serveur à serveur.

Les modes de remise disponibles pour une transaction PayPal sont les suivants :

  • Mode annulation : mode par défaut, il permet de remiser la transaction à une date prédéfinie, appelée délai de capture. Lorsque ce délai de capture est atteint, la remise est automatiquement envoyée. Ce délai est paramétré via le champ captureDay , sa valeur par défaut est 0 (paiement en fin de journée).
  • Mode validation : vous devez valider la transaction pour déclencher la remise. Un délai de capture doit aussi être défini. Lorsque ce délai de capture est atteint ou dépassé, vous ne pourrez plus valider la transaction, celle-ci expirera donc automatiquement.
  • Mode immédiat : l'autorisation et la remise sont exécutées en ligne simultanément.

Le diagramme ci-dessous explique les différents états par lesquels peuvent passer les transactions selon le mode de capture choisi :

Effectuer un paiement PayPal avec Sips Paypage

La cinématique de paiement pour Sips Paypage est décrite ci-dessous :

Paramétrer la requête de paiement

Aucune information spécifique n'est requise pour soumettre une requête de paiement PayPal, cependant, les champs ci-dessous ont un comportement particulier :

Nom du champ Remarques / règles
captureDay Date de remise demandée (entre 0 et 29 pour PayPal).
customerLanguage Permet de choisir la langue utilisée sur les pages Sips et PayPal (en anglais par défaut sur PayPal).
paymentMeanData.PayPal.invoiceId Numéro de commande PayPal. Le contrôle d'unicité est effectué par PayPal.
paymentMeanData.PayPal.addrOverride Permet d'effacer l'adresse du client enregistrée par PayPal ou de cacher cette adresse sur les pages PayPal.
paymentMeanData.PayPal.landingPage Permet de ne pas afficher le formulaire d'inscription à PayPal lorsque le client est redirigé sur le site PayPal.
paymentMeanData.PayPal.mobile Indique si le terminal utilisé est un mobile (permet de rediriger le client directement vers le site PayPal mobile).
paymentMeanData.PayPal.dupFlag Permet de dupliquer la transaction. La valeur par défaut est « false » (ne peut être dupliqué).
paymentMeanData.PayPal.dupDesc Permet d’indiquer le motif d’une duplication potentielle lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ». Les détails de la transaction seront affichés sur votre compte PayPal.
paymentMeanData.PayPal.dupCustom Champ libre à votre disposition. Il est pris en compte lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ».
paymentMeanData.PayPal.dupType Définit le type de duplication. La valeur par défaut est « InstantOnly ». Pris en compte lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ».

Analyser la réponse

Le tableau suivant récapitule les différents cas de réponse à traiter :

État Champs de la réponse Action à réaliser
Paiement accepté

responseCode = 00

acquirerResponseCode = 00

Vous pouvez livrer la commande.
Refus bancaire acquéreur

responseCode = 05

L’autorisation est refusée pour un motif non lié à la fraude.

Vous pouvez proposer à votre client de payer avec autre moyen de paiement en générant une nouvelle requête.

Refus fraude acquéreur

responseCode = 34

Autorisation refusée pour cause de fraude.

Ne livrez pas la commande.

Paiement en attente de confirmation

responseCode = 60

Vous devez attendre la mise à jour automatique du statut de la transaction vers un état final avant de décider d’expédier la commande. Pour ces transactions, il est nécessaire d’utiliser les journaux de transaction pour décider de continuer le traitement de la commande.
Refus nombre max essais atteint

responseCode = 75

L’acheteur a fait plusieurs tentatives qui ont toutes échouées.
Refus suite problème technique

responseCode = 90, 99

acquirerResponseCode = 90 à 98

Problème technique temporaire lors du traitement de la transaction.

Proposez à votre client de refaire un paiement ultérieurement.

Pour connaître l'intégralité des codes réponses ( responseCode ) et codes réponses acquéreur ( acquirerResponseCode ), veuillez-vous référer au document "Dictionnaire des données".

Gérer les refus

Lors d’un refus, PayPal détermine si le client peut utiliser un autre moyen de paiement enregistré sur son compte. Si c’est le cas, PayPal transmet une information particulière qui permet à Sips de rediriger à nouveau le client vers PayPal pour effectuer une nouvelle tentative.

Cette fonctionnalité vous permet d’augmenter votre taux de conversion dans le cas d'un paiement refusé car elle évite que le client revienne sur votre site Web puis relance à nouveau tout le processus de paiement.  

Paiement OneClick

Vous avez la possibilité d’accepter des paiements OneClick avec PayPal sur Sips Paypage . Vous devez avoir souscrit au service Sips OneClick PayPal et demander à PayPal de vous autoriser à dupliquer les transactions (cf. paragraphe Activer le paiement OneClick ).

Vous devez ensuite transmettre le champ merchantWalletId associé à votre client dans chaque requête de paiement.

La page suivante est alors affichée lors de l’enrôlement d’un compte PayPal dans le wallet Sips :

Si un compte PayPal a déjà été ajouté dans le wallet Sips alors la page de sélection suivante sera affichée et le paiement sera validé en un seul clic :

Effectuer un paiement PayPal avec Sips Office

Le processus de paiement pour Sips Office est décrit ci-dessous :

Initialiser un paiement (PaymentProviderInitialize)

L’initialisation d’un paiement PayPal est effectuée en appelant la méthode paymentProviderInitialize .

Requête d’initialisation du paiement

Les champs génériques suivants sont définis dans le cas d’une initialisation de paiement PayPal :

Nom du champ Remarques / règles Exemple
captureMode Peut prendre la valeur IMMEDIATE dans le cas d’une transaction PayPal. IMMEDIATE
captureDay Entre 0 et 29. 0
amount Montant en centime. 10000
customerLanguage La langue fournie est utilisée pour définir la langue utilisée sur le site de PayPal (langue par défaut : anglais).
paymentMeanBrand Doit être valorisé avec la valeur PAYPAL. PAYPAL
merchantReturnUrl Url de retour du marchand.

Les champs spécifiques PayPal qui peuvent être transmis sont les suivants :

Nom du champ Remarques / règles
paymentMeanData.PayPal.invoiceId Numéro de commande PayPal. Le contrôle d'unicité est effectué par PayPal.
paymentMeanData.PayPal.addrOverride Permet de surcharger l'adresse de l'internaute enregistrée par PayPal ou de cacher cette adresse sur les pages PayPal.
paymentMeanData.PayPal.landingPage Permet de ne pas afficher le formulaire d'inscription à PayPal lorsque l’internaute est redirigé sur le site PayPal.
paymentMeanData.PayPal.mobile Indique si le terminal utilisé est un mobile (permet de rediriger l’acheteur directement vers le site PayPal mobile).
paymentMeanData.PayPal.dupFlag Permet de dupliquer la transaction. La valeur par défaut est « false » (ne peut être dupliqué).
paymentMeanData.PayPal.dupDesc Permet d’indiquer le motif d’une duplication potentielle lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ». Les détails de la transaction seront affichés sur votre compte PayPal.
paymentMeanData.PayPal.dupCustom Champ libre à la disposition du commerçant. Il est pris en compte lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ».
paymentMeanData.PayPal.dupType Définit le type de duplication. La valeur par défaut est « InstantOnly ». Pris en compte lorsque la valeur de paymentMeanData.PayPal.dupFlag est « true ».

Réponse d’initialisation du paiement

Les champs suivants sont retournés dans le cas d’un paiement PayPal :

Nom du champ Remarques / règles Exemple
responseCode Code réponse 00
redirectionData Données de redirection RSs7cZyL[…]LyNK5ACo
redirectionUrl URL de redirection vers le site PayPal
messageVersion Version du message 0.1

Rediriger le client vers le site PayPal

Le client doit être redirigé vers l’URL « redirectionUrl » fournie en réponse de la méthode « paymentProviderInitialize ». Cette redirection consiste à effectuer un appel POST sur l’URL « redirectionUrl » obtenue dans la réponse à l’initialisation de paiement. Les paramètres POST à transmettre sont « redirectionData » et « messageVersion » obtenus également dans la réponse à l’initialisation de paiement.

A la fin de la cinématique de paiement, le client est redirigé sur l’URL fournie dans la requête d’initialisation, « merchantReturnUrl ». Les champs suivants sont transmis en POST et doivent être récupérés pour finaliser le paiement :

Nom du champ Remarques / règles Exemple
responseCode Code réponse du processus 00
redirectionData Données de redirection RSs7cZyL[…]LyNK5ACo
messageVersion Version du message utilisé 0.1
amount Montant de la transaction en centimes 1000
merchantId Identifiant de la boutique 002474849505153
transactionReference Référence de la transaction TEST0231268482123
transactionId Identifiant de la transaction 123456
transactionDate Date de la transaction 20150707

Finaliser un paiement (PaymentProviderFinalize)

Cette dernière étape vous permet d’obtenir le statut du paiement. Les paramètres obtenus lors de la redirection après la cinématique de paiement sur le site PayPal sont à transmettre lors de cet appel. La méthode utilisée pour finaliser un paiement est « paymentProviderFinalize ».

Requête de finalisation du paiement

Les champs spécifiques suivants doivent être fournis par vous dans la requête de finalisation pour un paiement PayPal.

Nom du champ Remarques / règles Exemple
redirectionData Données de redirection (récupéré au paragraphe "Redigirer le client vers le site PayPal"). RSs7cZyL[…]LyNK5ACo
messageVersion Version de message 0.1

Réponse de finalisation du paiement

Les champs suivants sont retournés pour un paiement PayPal :

Nom du champ Remarques / règles Exemple
paymentMeanBrand La valeur de ce champ est toujours « PAYPAL ».
responseCode Code réponse du serveur Sips . 00
transactionStatus Etat de la transaction. TO_CAPTURE

Récupération des informations de l’acheteur (optionnel)

La méthode « paymentProviderGetContext » est optionnelle et vous permet de récupérer des informations concernant l’acheteur et le paiement en cours. La requête est directement soumise à PayPal et permet notamment d’obtenir des informations sur l’adresse de livraison, l’e-mail de l’acheteur ou encore le statut du paiement chez PayPal.

Cette méthode doit être appelée après la redirection de l’acheteur de la page PayPal vers le site du marchand et avant la finalisation d’un paiement. Si elle est appelée après la finalisation, PayPal peut refuser la restitution d’informations.

Requête de récupération des informations de l’acheteur

Vous trouverez ci-dessous la liste des champs devant être remplis pour cette méthode :

Nom du champ Remarques / règles Exemple
redirectionData Données de redirection (Récupéré en sortie de l’initialisation du paiement). RSs7cZyL[…]LyNK5ACo
messageVersion Version de message (Récupéré en sortie de l’initialisation du paiement). 0.1

Réponse de récupération des informations de l’acheteur

Nom du champ Remarques / règles
paymentMeanData.PayPal.token Le token PayPal permet la réalisation du paiement.
paymentMeanData.PayPal.payerId Identifiant unique de l’acheteur (donnée PayPal).
paymentMeanData.PayPal.payerStatus

Statut de l’acheteur (donnée PayPal).

  • verified
  • unverified
paymentMeanData.PayPal.payerBusiness Nom d’enseigne de l’acheteur.
paymentMeanData.PayPal.paymentStatus
Statut du paiement (donnée PayPal).
  • PaymentActionNotInitiated
  • PaymentActionFailed
  • PaymentActionInProgress
  • PaymentActionCompleted
paymentMeanData.PayPal.payerSuffix Suffixe de l’acheteur.
paymentMeanData.PayPal.deliveryAddressStatus
  • none
  • Confirmed
  • Unconfirmed

Gérer vos transactions PayPal

Note: Toute opération de gestion de caisse concernant une transaction PayPal doit obligatoirement être effectuée par l'intermédiaire des outils Sips . L'initiation d'opérations de gestion de caisse depuis votre compte PayPal provoquera des incohérences entre les états des transactions de Sips et celles de PayPal.

Opérations de caisse disponibles

Les opérations suivantes sont disponibles sur les transactions PayPal :

Gestion de caisse
Annulation V
Validation V
Remboursement V
Les demandes de remboursement PayPal sont prises en compte immédiatement.
Le remboursement peut être effectué jusqu'à 60 jours après l'achat. Toute demande de remboursement après ce délai a pour conséquence l'envoi du code réponse Sips « 12 ».
Duplication V Voir le paragraphe Dupliquer une transaction PayPal .
Recyclage X
Crédit X

Le diagramme ci-dessous vous permet de savoir quelle opération de gestion de caisse est disponible lorsqu'une transaction est dans un état donné :

Dupliquer une transaction PayPal

Le processus de duplication d'une transaction nécessite que la transaction initiale soit éligible à la duplication. Quatre champs doivent être transmis dans la requête de paiement initiale :

  • paymentMeanData.PayPal.dupFlag
  • paymentMeanData.PayPal.dupDesc
  • paymentMeanData.PayPal.dupType
  • paymentMeanData.PayPal.dupCustom
Note: PayPal doit avoir autorisé votre compte à dupliquer les transactions. Contactez PayPal si vous avez besoin de cette fonctionnalité.

Marqueur de duplication

Pour marquer la transaction comme éligible à la duplication, vous devez l'indiquer comme telle dans le message de création envoyée à Sips donnant au champ paymentMeanData.PayPal.dupFlag la valeur « true ».

Description

Le champ dupDesc est facultatif et n'est utilisé que si le champ dupFlag a pour valeur « true ».

Ce champ est utilisé pour ajouter une description au processus de duplication. La description sera affichée sur la page de détails du paiement PayPal.

Note: la longueur de champ est limitée à 127 caractères (ANS).

Type

Le champ dupType est facultatif et n'est utilisé que si le champ dupFlag a pour valeur « true ».

Les valeurs acceptées sont :

  • ANY : vous acceptez n'importe quel moyen de paiement pour l'accord de facturation, même si le mouvement des fonds vers votre compte peut prendre quelques jours. Cela inclut les chèques, en plus des cartes de crédit et de débit, et du solde PayPal.
  • INSTANTONLY : les moyens de paiement que vous acceptez sont limités aux cartes de crédit et de débit ainsi qu'au solde PayPal (vous forcez un paiement immédiat).
Note: par défaut, la valeur de ce champ est INSTANTONLY.

Personnalisation

Le champ dupCustom est facultatif et n'est utilisé que si le champ dupFlag a pour valeur « true ».

Ce champ est un champ d'annotation personnalisé qui vous est réservé, il est affiché sur le détail de vos transactions dans votre back-office PayPal.

Consulter vos transactions PayPal

Journaux

Les journaux mis à disposition par Sips vous permettent d’avoir une vision exhaustive et consolidée de vos transactions, opérations de caisse, situation comptable et impayés. Vous pouvez utiliser ces informations pour enrichir votre système d’information.

La disponibilité des transactions PayPal pour chaque type de journal est récapitulée dans le tableau ci-dessous :

Disponibilité des journaux
Journal des transactions V
Journal des opérations V
Journal de rapprochement des transactions V
Journal de rapprochement des impayés V
Attention: pour les transactions PayPal, le champ paymentMeanBrand est renseigné avec la valeur PAYPAL.
Pour inclure les transactions PayPal dans les journaux de rapprochement des impayés, vous devez activer l'option via votre compte PayPal .

Sips Office Extranet

Vous pouvez consulter vos transactions PayPal et effectuer différentes opérations de gestion de caisse grâce à Sips Office Extranet .

Voici le détail d’une transaction PayPal. Certaines informations spécifiques sont affichées comme le numéro d’autorisation PayPal.