Les fonctions

Le cas des remboursements

Vous pouvez réaliser le remboursement de vos transactions PayPal depuis Payline par le Web Service « doRefund » ou par notre centre d'administration.
La limite du montant des remboursements correspond par défaut au montant de la transaction d'origine.
Si vous souhaitez modifier ces limites, vous pouvez contacter votre responsable commercial PayPal.

Journaux de transactions Payline

Toutes les transactions PayPal, acceptées, refusées et impayés, apparaissent dans le fichier « Liste des transactions » de Payline.
Ce fichier peut être généré manuellement depuis notre centre d'administration ou automatiquement transmis sur vos serveurs par transfert de fichier sécurisé.

Récupération des informations de PayPal

Certaines informations provenant de PayPal sont retournées au commerçant dans la structure PartnerAdditionalData de l'objet transaction avec une structure JSON contenant :
- Email du compte acheteur PayPal ;
- Statut du compte (verified/unverified) ;
- Pays du compte (ISO3166) ;
- Identifiant de la transaction PayPal est restitué dans a balise referenceID pour les version de l'API supérieure ou égale à 16.

Le champ est valorisé pour chaque transaction réalisée avec PayPal si au moins un des 3 informations est disponible et pour une version du service 16 ou supérieur avec le typeCarte = PAYPAL.

Cette structure sera retourné dans les réponses des services : getTransactionDetails et getWebPaymentDetails.

Exemple de la structure

<AdditionalData>
    {"login":"VALEUR_EMAIL",
     "accountStatus":"VALEUR_PAYERSTATUS",
     "accountCountryCode":"VALEUR_COUNTRYCODE"}
</additionalData>

Les web services GetCards et GetWallet contennent les mêmes informations du ou des comptes PayPal contenu dans le wallet interrogé si un ou plusieurs comptes PayPal y sont enregistrés.

Les informations sont les mêmes que celles retournées dans le GetWebPaymenDetails.

Instant Payment Notification (IPN)

Toutes les modifications d'une autorisation envoyée par Payline dans le centre administration de PayPal, seront notifiées à Payline par PayPal.

Personnalisation PayPal

Le nom commercial et le logo seront envoyés à PayPal. Ces paramètres sont configurés dans le contrat du moyen de paiement.
La langue sera configurée lors de l'appel au service de paiement.

SoftDescriptor PayPal 

L'information affichée sur le relevé de compte de l'acheteur et sur le ticket de paiement peut être transmise à PayPal.
Le champ softdescriptor des objets Transaction et Payment de l'API Payline est étendu à 127 caractères spécifiquement pour PayPal.

Champs Obligatoires

Pour les pays suivant Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA; l'adresse de livraison n'est pas envoyée si l'un des champs obligatoires est manquant : nom, rue, ville, pays et état.

Address.Name, Address.Street1, Address.CityName, Address.gountry, Address.Country, Address.State.

Intégration du paiement en mode widget / page web

Étape 1 : Utilisation de l'interface Web/LightBox

Pour utiliser PAYPAL dans Payline, vous bénéficiez des fonctions de paiement suivantes :

• • doWebPayment
  • getWebPaymentDetails

Le web service doWebPayment

La fonction « doWebPayment » permet d'initialiser une transaction de paiement web avant de rediriger votre client sur les pages de paiement Payline :

• • Avec un paiement immédiat en indiquant les champs « payment.Action » à 101, « payment.Mode » à CPT et « payment.ContractNumber » avec le numéro de contrat PAYPAL. Payline réalise une demande d'autorisation auprès de l'acquéreur et dans le cas d'un accord, Payline valide automatiquement le paiement ;
  • Avec un paiement à l'expédition en indiquant les champs « payment.Action » à 100, « payment.Mode » à CPT et « payment.ContractNumber » avec le numéro de contrat PAYPAL. Pour déclencher le paiement, vous devez réaliser un appel au web service « doCapture » avec votre numéro de contrat PAYPAL et l'identifiant de votre transaction d'autorisation initiale.
    
    

Le web service getWebPaymentdetails

Pour réaliser une demande de résultat de la transaction de paiement, Payline met à votre disposition ce web service. Vous devez transmettre le jeton d'authentification délivré par Payline lors de la demande d'initialisation (résultat de la fonction doWebPayment) pour obtenir un résultat détaillé du paiement.

Mode d'intégration

Payline offre la possibilité au commerçant de définir depuis son compte commerçant le mode d'affichage des pages PayPal : mode redirection plein écran ou mode lightbox.
Payline redirigé l'acheteur sur les pages de paiement PayPal.

Étape 2 : Gérer vos encaissements PayPal avec Payline

Vous pouvez réaliser les opérations d'encaissement correspondant au montant initial de vos transactions PayPal :

• • Validations partielles ou intégrales
  • Remboursements partiel ou intégral

Intégration du paiement 1 Clic avec un portefeuille virtuel

Le principe

Le principe du paiement en 1 clic est de permettre au consommateur de payer chez un commerçant sans avoir à s'authentifier sur PayPal à partir du deuxième achat.

• Lors du choix de PayPal dans la première commande, le consommateur est invité à donner son accord pour de futurs achats en '1 clic' ;
• Si le paiement est mené à son terme, Payline enregistre les informations d'agrément de paiement de PayPal ;
• À partir de la deuxième commande, le choix du moyen de paiement PayPal rappelle l'accord du consommateur pour de futurs achats en '1 clic'. La simple validation du choix du moyen de paiement déclenche le paiement.

Les fonctionnalités

Payline propose au commerçant de définir depuis son compte commerçant s'il autorise ou non les paiements en 1 clic et propose la gestion par l'API :

• Demande de l'accord du consommateur PaPayPalpal
  • Payline affiche la case à cocher pour collecter l'accord du consommateur sur la page choix du moyen de paiement gérée par Payline ;
  • Dans le cas où le choix du moyen de paiement est proposé sur la boutique en ligne, le commerçant renseigne le champ walletID de l'API Payline lorsqu'il obtient l'accord du consommateur.
    
    
• Enregistrement et gestion de la référence de l'accord
  • Payline enregistre la référence de l'accord dans le portefeuille virtuel Payline (wallet) utilisé pour le paiement 1 clic via carte bancaire. De ce fait, pour le commerçant l'utilisation du paiement en 2 clics ne nécessite aucun développement supplémentaire s'il utilise déjà cette API.
  • En complément, Payline fournit au commerçant une page de « gestion » des moyens de paiement enregistrés (1 clic visa/mastercard et 2 clic PayPal). Pour faire fonctionner PayPal dans cette fonction.

Les limites sont les suivantes :

• Type autorisation+validation (action=101) et autorisation (action=100) ;
• Seule la fonction suppression est disponible avec le service ManageWebWallet ;
• Un seul contrat PayPal par portefeuille (External_Wallet_ID) est autorisé.
• L'option de Activation du portefeuille doit être activé dans la configuration du moyen de paiement Payline.

Un identifiant de wallet correspond à un External_Wallet_ID, ceci suffit à identifier le wallet PayPal courant qui est unique.

Les web services 

L'option '1-clic' est utilisée par le commerçant si le « doWebPayment » contient un identifiant de wallet et un seul contrat VAD.
Il existe un accord de paiement s'il existe un Wallet avec External_Wallet_ID égal aux arguments reçus via le « doWebPayment » et si la case à cocher de l'accord de paiement a été sélectionnée.
L'accord d'enregistrement peut être transmis en paramètre de la fonction doWebPayment avec un PrivateData dont la clé est recordingAgreement, la valeur est 'Y'.
Le service doImmediateWalletPayment est également disponible pour réaliser les paiements : SI l'option '1-clic' est configurée et activée et s'il existe un accord de paiement.

Voir l'objet buyer de l'API Payline.

1^er paiement : exemple de page de redirection avec utilisation du portefeuille virtuel

page de paiement v1 :

avec le widget :

Paiement suivant : exemple de page de redirection avec utilisation du portefeuille virtuel

Gestion du portefeuille

Le service manageWebWallet permet à l'acheteur la suppression du moyen de paiement PayPal d'un portefeuille.

Pour configurer PayPal

Vous devez sélectionner deux nouvelles options sur votre compte Paypal dans vos environnement d'homologation et  de production.

Pour configurer Payline

Vous devez configurer le point de vente avec les options suivantes :

Intégration du second moyen de paiement en cas d'échec

Le principe de cette amélioration consiste à proposer au consommateur d'utiliser un autre mode de paiement en cas d'échec de paiement.

• Cette fonction est configurable par le commerçant.
• Payline permet au commerçant de définir depuis son compte commerçant sur le contrat du moyen de paiement dans le centre administration, si PayPal propose au non un 2nd moyen de paiement en cas d'échec sur le 1er.
• PayPal renvoi un code particulier lorsque le paiement est refusé pour motif de plafond atteint. Sur réception de ce code Payline redirige le consommateur vers l'url de redirection PayPal et lui présente une page de choix d'un autre moyen de paiement.

Intégration PayPal en mode ExpressCheckOut

PayPal propose à ses commerçants le mode ExpressCheckOut, en intégrant un bouton spécifique directement sur la page de la commande. Avec cette méthode, le consommateur peut acheter sur le site commerçant sans avoir à saisir ses données personnelles (nom, prénom, adresses de livraison et de facturation, moyen de paiement…), voire même sans devoir au préalable créer un compte acheteur sur le site. Le commerçant n’a plus qu'à rediriger le consommateur vers une page de paiement : Payline va directement injecter les éléments dans la page du site commerçant.

Lorsque le consommateur se trouve à l’étape de la revue de commande, le commerçant peut proposer des modifications : changement des adresses, du mode de livraison,… Il est également possible de proposer des services additionnels (assurance, produit complémentaire, …).

Les fonctions disponibles

• Demande d'autorisation ;
• Demande d'autorisation-validation ;
• Demande d'encaissement partielle et totale ;
• Demande de remboursement partiel et total ;
• Fonctionne en mode Widget et en mode à redirection avec la Page Web de Paiement version 2.

Le parcours utilisateurs

L'expérience utilisateur d'un paiement se résume à :

1. Le consommateur sélectionne son produit et clique sur le bouton PayPal ExpressCheckOut ;
   
2. Il est redirigé sur la page PayPal, il saisit son login et mot de passe ;
3. Il confirme son moyen de paiement et son adresse de livraison ;
4. Il confirme sa commande : panier et montant ;
5. Le site commerçant affiche la facture ou propose un nouveau tarif de livraison suivant le mode de paiement sélectionné.
   

Les pages de paiement

Étape 1 : Validation du panier

• Le bouton CheckOut PayPal est inséré dans la page de validation du panier sur le site du commerçant.

• Inutile de créer un compte pour le consommateur : données personnelles, adresse de livraison, facturation...

Étape 2 : Authentification du consommateur

• Le consommateur est redirigé sur la page d'authentification PayPal avec son email.

Étape 3 : Validation de l'adresse et du moyen de paiement

• Le consommateur sélectionne son adresse et son moyen de paiement.

Étape 3 : Finalisation du paiement

• • Lorsque le consommateur se trouve à l’étape de la revue de commande, le commerçant peut proposer des modifications : changement des adresses, du mode de livraison, …
    Il est également possible de proposer des services additionnels (assurance, produit complémentaire, …). Le montant de la commande ainsi que les informations de commandes peuvent changer et doivent être enregistrés dans la base de données.

  • Page de finalisation de la commande : la transaction est effective et enregistrée une fois que acheteur effectue l'action de finaliser sa commande.

    L’API JavaScript de Payline autorise ces changements. Le commerçant peut passer les modifications à Payline avant validation du paiement (le contrat doit être paramétré pour ce cas).

Comment proposer PayPal ExpressCheckOut

Vous devez entrer en contact avec notre équipe support pour demander l'activation de ce moyen de paiement dans votre compte commerçant.

Une fois le moyen de paiement activé, il vous suffit d'utiliser l'API WebPayment et les fonctions suivantes : 

• doWebPayment ;
• getWebPaymentDetails ;
• getTransactionDetails ;
• transactionsSearch;
• doRefund, doCapture et doReset.

En mode widget, lors de l'appel du doWebPaiement, seul email du buyer sera pris en compte par Payline, les informations du buyer seront retournées par PayPal.
Ensuite vous devez récupérer le Token et préciser l'option data-template="shortcut".

<div id="PaylineWidget"
     data-token="1mzreM6MGwh2GZO276317895190386597" data-template="shortcut"
     data-event-didshowstate="showStateFunction"
</div>

En retour de PayPal, le commerçant pourra utiliser l'API JavaScript de Payline : voir l'intégration Widget avec les events, fonctions API et CallBack.
Payline préconise de contrôler l'état de la transaction avec l'option data-event-didshowstate, ceci dans le but de récupérer les informations de l'acheteur, éventuellement proposer d'autres options à la commande et surtout de finaliser la transaction avec la fonction finalizeShortcut().

• Payline.API.getBuyerShortcut() : récupérer les informations du consommateur ;
• Payline.API.updateWebpaymentData() : mettre à jour la commande ;
• Payline.API.finalizeShortcut() : finaliser la commande.

Exemple de  la fonction  showStateFunction permettant « d’intégrer » la cinématique Shortcut :

function showStateFunction(state) {   
     if ("PAYMENT_METHODS_LIST_SHORTCUT" == state.state) {
         //traitement particulier au besoin de l’intégration du commerçant
         ...
     }
     if ("PAYMENT_TRANSITIONAL_SHORTCUT" == state.state) {
        // 1) Mise à jour du montant:
        // 1.a) Preparation de JSON
        var updateCart = {
          "payment": {
             "amount": "1500",
             "currency": "978"
           }
        };
        // 1.b) Mise à jour du webPaiement via api JS   
        Payline.Api.updateWebpaymentData(token, updateCart, function (response) {
          if (response._status) {
          // Traiter la reponse au besoin
          // Appeler la fonction finalizeShortcut pour mettre à jour le panier
          // La mise à jour du panier devrait être faite suite au click sur un bouton payer géré par le marchand
          ...
        }
      });
        // 2) Finalisation du paiement Shortcut
        Payline.Api.finalizeShortcut();
     }
     if ("PAYMENT_SUCCESS" == state.state) {
        //traitement particulier au besoin de l’intégration du commerçant
     }
 }

Comment configurer votre compte

De la même manière qu'un contrat PayPal, voir l'intégration PayPal.

Le commerçant doit vérifier les options et contrôler la phase pilote :

Les Codes retour 

Monext Online vous informe du résultat d’un paiement via le ShortMessage, selon le mode d'intégration proposé par le moyen de paiement. 

• pour l'API WebPayment avec le service getWebPaymentDetails,
• pour l'API DirectPayment en réponse du service doAuthorization de manière synchrone ou getTransactionDetails en réponse asynchrone.

Les états retournés :

• Le paiement est accepté avec l'état ACCEPTED et le code retour 00000.
• Le paiement est refusé avec l'état REFUSED. Le code varie en fonction du motif de refus (Par exemple : 01xxx pour une raison bancaire ou 04xxx pour une suspicion de fraude).

La gestion des états et des codes retour sont listés ici.

Le tableau ci-dessous permet de recenser l'ensemble des codes et messages de retour Payline pour PAYPAL ainsi que leur destinataire.

Note :

• Lorsque Payline n'a aucun retour du consommateur une fois redirigé chez PayPal, par exemple : lorsque le navigateur est fermé, vous recevrez une notification de refus avec le motif CANCELLED et un code 02319. 

• Le paiement est accepté avec réserve  (Etat temporaire) : l'état de l'opération de type commande est PENDING_RISK avec le code 02017.

• Le paiement a été acquitté par Paypal et mis en attente pour une prise de décision ultérieure (Etat temporaire)  : l'état de l'opération de type commande est  ONHOLD_PARTNER avec le code 02016.

Pages associées

• Page:
  ANCV Chèque Vacances Connect
• Page:
  ApplePay - Intégration
• Page:
  Centre Administration - Dossiers de paiement
• Page:
  Centre Administration - Echéances
• Page:
  Centre Administration - Paiement par portefeuille
• Page:
  Centre Administration - Portefeuille
• Page:
  Click to Pay
• Page:
  Comment réaliser un paiement récurrent ou par abonnement ?
• Page:
  Demande d'information
• Page:
  DP - Gestion des portefeuilles