Principe
Le Mode in-Shop utilise des iframes pour afficher le formulaire de paiement en superposition (overlay) de votre boutique avec des onglets. Lorsque ce mode est utilisé, votre boutique est grisée et le formulaire de paiement apparaît flottant au dessus de votre boutique.
Intégration
L'intégration, extrêmement facile, s'effectue en uniquement 3 étapes :
- Initialisation du paiement : vous devez utiliser la fonction doWebPayment de l'API Web Payment pour initialiser un paiement sur les pages de paiement Payline.
- Ajout d'un script et d'une balise <DIV> dans le corps de votre page web : Payline va se servir de cette balise pour afficher le formulaire de paiement.
- Résultat du paiement : vous devez utiliser la fonction getWebPaymentDetails de l'API Web Payment pour obtenir le résultat du paiement.
La page HTML minimale pour générer un formulaire de paiement est la suivante :
<html> <head> <script src="https://homologation-payment.payline.com/scripts/widget-min.js"></script> </head> <body> <div id="PaylineWidget" data-token="the token obtained in doWebPayment Response" data-template="column"/> </body> </html>
Le #paylineToken# est le jeton d'authentification obtenu dans la réponse à la demande d'initialisation d'un paiement (doWebPayment). Afin d'éviter qu'une nouvelle initialisation soit réalisée lors de chaque actualisation de la page, vous devez soit utiliser une session sur votre serveur pour le stocker, ou alors vérifier si l’URL courante contient déjà un jeton de paiement dans un paramètre GET nommé paylinetoken. Voici un exemple pour réutiliser le jeton présent dans l'URL :
<? $paylineToken = (is_empty($_GET['paylinetoken'])) ? $_GET['paylinetoken'] : createNewWebPayment(); ?>
Pour obtenir la mise en forme du formulaire de paiement, vous devez intégrer la feuille de style CSS Payline en ajoutant la ligne suivante dans la balise <head> :
<link href="https://homologation-payment.payline.com/styles/widget-min.css" rel="stylesheet" />
Les URLs du script et de la CSS sont différents entre les environnements de test et de production. Nous vous conseillons de les configurer dans des variables d'environnements.
Des attributs additionnels que vous pouvez utiliser dans la balise <div> permettent de personnaliser l'affichage du formulaire. Par exemple; si vous ne souhaitez pas que le formulaire de paiement s'affiche automatiquement lors de l'affichage de votre page :
| Paramètre | Description | valeur |
|---|---|---|
| data-template | Le nom du template à utiliser pour l'initialisation du formulaire. |
|
| data-auto-init | Définit si le formulaire doit s’initialiser dès que la page web a fini de se charger (auto-init à « true »), ou s’il doit attendre un demande d’initialisation (auto-init à « false ») |
|
API JavaScript
Afin d’interagir avec le formulaire de paiement, Payline propose une API en JavaScript pour que vous gardiez la main sur le formulaire. Les fonctions disponibles sont :
| Fonction | Description |
|---|---|
init() | demande d'initialisation du formulaire de paiement. Lors de l'initialisation, le widget Payline construit le formulaire en fonction du contexte de la demande de paiement: montant, moyen de paiement proposé, etc. |
| show() | demande d'affichage du formulaire de paiement. |
| hide() | demande de masquage du formulaire de paiement. |
Exemple pour masquer, puis afficher le formulaire de paiement :
Payline.Api.hide(): void Payline.Api.show(): void
Personnalisation
Personnaliser le style du formulaire de paiement est possible en surchargeant la feuille de style fournit par défaut par Payline. Les possibilités de personnalisation sont infinies, voici quelques exemples simples :
| Paramètre | Description |
|---|---|
#PaylineWidget .pl-pay-btn { #PaylineWidget .pl-pay-btn:hover { | la couleur du bouton de paiement |
#PaylineWidget .pl-body { | la couleur de fond du formulaire |
#PaylineWidget .pl-pmContainer { | la couleur de la zone moyen de paiement |
Fonctionnalités avancées
Ajout d'un moyen de paiement non géré par Payline
Vous souhaitez proposer à vos clients un moyen de paiement que vous gérez vous même, par exemple une carte de fidélité propre à votre enseigne.
L'attribut additionnel data-custompm que vous pouvez utiliser dans la balise <div> permet de personnaliser l'affichage du formulaire. Par exemple, si vous ne souhaitez pas que le formulaire de paiement s'affiche automatiquement lors de l'affichage de votre page :
| Paramètre | Description | Exemple |
|---|---|---|
| data-custompm | Le nom de la fonction javascript qui va générer le formulaire du moyen de paiement non géré par Payline | maFonctionJavascript |
Cette fonction est appelée durant le processus d’initialisation du Widget, donc soit au onload du body, soit à l’appel de Payline.Api.init() si data-auto-init="false" a été spécifié.
La fonction doit retourner un tableau d’objet, chacun de ces objets représentant un moyen de paiement.
Dans chacun de ces objets, on doit retrouver les attributs obligatoires suivants :
- paymentMethodId : chaine de caractère destinée à identifier le moyen de paiement. Cette chaine, après avoir subi un lowercase, sera utilisée concaténée dans des id HTML, et doit donc respecter les normes associées. Utile pour appliquer du CSS à votre
- html : chaine de caractère qui sera injecté dans le formulaire. Libre à vous de réutiliser ou non la structure HTML et les classes CSS que nous utilisons pour les moyens de paiement gérés par l’API.
Un attribut facultatif index (type numérique) peut aussi être spécifié pour insérer votre moyen de paiement au sein de la liste qui a été donnée lors du doWebPayment. Si index est absent, le moyen de paiement sera rajouté à la fin de la liste de moyens de paiement existante.
Par exemple, la fonction JavaScript suivante va ajouter un moyen de paiement personnalisé dont le formulaire sera composé d'un input simple ainsi que d'un bouton.
[id*="mycustompm"] span.pl-card-logo {
background:none; width: auto;
}
[id*="mycustompm"] span.pl-card-logo::before {
content:"Mon moyen de paiement";
}
Pour personnaliser le logo qui sera généré automatiquement par le script Payline, vous pouvez utiliser du CSS. Parce que le script Payline utilise le champ paymentMethodId de votre moyen de paiement personnalisé pour construire les identifiant HTML des éléments qui composeront votre moyen de paiement personnalisé, il est facile de cibler le logo avec des sélecteurs CSS tels que :
[id*="mycustompm"] span.pl-card-logo {
background:none; width: auto;
}
[id*="mycustompm"] span.pl-card-logo::before {
content:"Mon moyen de paiement";
}
Modifier le montant de la transaction entre l'initialisation et le paiement
Vous souhaitez améliorer l'expérience utilisateur, nous vous conseillons d'initialiser le paiement (via la fonction doWebPayment) le plus tôt possible dans le tunnel d'achat. Si possible, dès l'étape du choix du mode de livraison. En effet, vous gagnerez beaucoup lors du temps d'affichage de l'étape paiement. Cette façon de faire implique de pouvoir modifier le montant de la transaction après l'initialisation du paiement.
La modification du montant pourra alors être réalisée par un appel HTTP contenant une trame en JSON avec les données qui viendront écraser ce qui a pu être spécifié dans le doWebPayment.
L’URL à appeler sera :
- En homologation : https://homologation-payment.payline.com/token/{leToken}/webPayment
- En production : https://payment.payline.com/token/{leToken}/webPayment
La requête HTTP devra utiliser la méthode PUT, et devra spécifier dans son header le Content-Type : application/json ; le corps de la requête, lui, devra contenir les données à modifier formatées en JSON.
La structure de l’objet JSON à envoyer est décrite par le tableau qui suit. Aucun attribut de cet objet JSON n’est obligatoire, sauf exception explicitée dans le tableau. Il est donc possible de n’envoyer qu’une partie de la structure à votre convenance.
Objets niveau 1 | Objet niveau 2 | Objet niveau 3 | Objet niveau 4 |
|---|---|---|---|
payment | amount | ||
currency | |||
order | amount | ||
currency | |||
taxes | |||
deliveryTime | |||
deliveryMode | |||
deliveryExpectedDate | |||
deliveryExpectedDelay | |||
details | orderDetail | ref | |
| price (obligatoire à l’envoi d’un order detail) | |||
quantity | |||
comment | |||
category | |||
brand | |||
subcategory1 | |||
subcategory2 | |||
additionalData | |||
taxRate | |||
orderDetail | ref | ||
… | |||
buyer | shippingAddress | title | |
| name | |||
lastName | |||
firstName | |||
street1 | |||
street2 | |||
cityName | |||
zipCode | |||
country | |||
phone | |||
state | |||
county | |||
phoneType | |||
billingAddress | title | ||
name | |||
lastName | |||
firstName | |||
street1 | |||
street2 | |||
cityName | |||
zipCode | |||
country | |||
phone | |||
state | |||
county | |||
phoneType |
Il est nécessaire de contrôler systématiquement le montant pris en compte pour la transaction.
Ce montant est disponible dans le champ payment.amount de la réponse à la fonction getWebPaymentDetails().
Par mesure de sécurité, cette fonction n'est pas activé par défaut. Si vous souhaitez l'activer, il vous faut cocher l'option dans l'écran de configuration de votre point de vente.
Liste des navigateurs compatibles
Le tableau ci-dessous liste les navigateurs qui sont compatibles avec les modes Lightbox et Intégré. Si un navigateur avec une version inférieure est détectée, le mode redirection est automatiquement utilisé pour afficher la page de paiement au consommateur.
| Navigateur | Version |
|---|---|
| Chrome | >=28 |
| Chrome Mobile | >=28 |
| Firefox | >=31 |
| Firefox Mobile | >=31 |
| Internet Explorer | >=9 |
| Internet Explorer Mobile | >=9 |
| Safari | >=6 |
| Safari Mobile | >=6 |
| Opera | >=24 |
| Opera Mobile | >=22 |
| Android Browser | >=4 |
Liste des moyens de paiement disponibles
Le tableau ci-dessous liste les moyens de paiements disponibles avec les modes Lightbox et Intégré. Tous les autres moyens de paiement sont disponibles avec le mode Redirection.
| CB | Carte Bancaire, Visa, Mastercard | |
| MCVISA | Visa, Mastercard | |
| AMEX | American Express | paiement comptant et en N fois |
| AMEX REC | American Express Smartbill | |
| 1EURO.COM | 1EURO.COM | |
| 3xCB | 3xCB Cofidis | |
| 3xONEY | 3xCB Oney | |
| BCMC | Bancontact Mistercard | Cartes co-brandée Maestro et cartes domestiques |
| ELV | ELV | |
| GIROPAY | Giropay | |
| IDEAL | IDEAL | |
| MAESTRO | Maestro | |
| MASTERPASS | Masterpass | un problème est identifié sur ce moyen de paiement |
| PAYLIB | Paylib | |
| PAYPAL | PayPal | |
| POSTFINANCE | Postfinance | |
| SOFORT | Sofort | |
| JCB | JCB | sans le dispositif JSecure |
| CA_DO_CARTE | CadoCarte | |
| CDGP | CDGP Cofinoga | |
| COFINOGA | Cofinoga | |
| CYRILLUS | Carte Cyrillus Finaref | |
| DINERS | Diners | |
| DISCOVER | Discover | |
| FNAC | Carte FNAC Finaref | |
| ILLICADO | ILLICADO | |
| KANGOUROU | Carte Kangourou Finaref | |
| KLARNA | KLARNA invoice | |
| LEETCHI | LEETCHI | |
| LYDIA | LYDIA | |
| MONEYCLIC | Moneyclic | |
| NEOSURF | Neosurf | |
| NETELLER | Neteller | |
| P24 | Przelewy 24 | |
| PAYSAFECARD | Paysafecard | |
| PRINTEMPS | Carte Printemps Finaref | |
| SDD | SDD | via Slimpay |
| SPIRIT_OF_CADEAU | Spirit of Cadeau | |
| TICKETSURF | TicketSurf | |
| TOTAL GR | Carte Total GR | |
| YANDEX | Yandex wallet | |
| SWITCH | SWITCH | |
| BOLETO | BOLETO BANCARIO |