Page tree
Skip to end of metadata
Go to start of metadata




The Widget integration (column / tab or Lightbox mode), takes place in only 3 steps :

  1. Initialization of payment : from your server you use the doWebPayment function of Web Payment API to initiate a payment on Payline payment pages.
  2. From web page, add a script and  <DIV> tag in body of your web page : Payline will use that tag to display the payment form.
  3. Payment Result : from your server you use the getWebPaymentDetails function of  Web Payment API to get payment result.

The minimum HTML page for generating a payment form is as follows:

   <script src=""></script>
 <div id="PaylineWidget" 
    data-token="the token obtained in doWebPayment Response" 

The data-token is the session token for authentication and is obtained in response to the request to initialize a payment (doWebPayment). In order to avoid that a new initialization is performed during each refresh of the page, you must either use a session on your server to store it, or check if the current URL already contains a payment token in a GET parameter named paylinetoken. Here is an example to reuse the token present in the URL:

Code PHP
<?php $paylineToken = ( is_empty($_GET['paylinetoken']) ) ? createNewWebPayment() : $_GET['paylinetoken']; ?>

Additional attributes that you can use in the <div> tag allow you to customize the display of the form. For example; if you do not want the payment form to appear automatically when your page is displayed :

The name of the template to use for initializing the form.
  • tab
  • column
  • lightbox
  • shortcut
Defines whether the form should initialize as soon as the web page has finished loading (auto-init to "true"), or if it must wait for an initialization request (auto-init to "false")
  • true
  • false

Function deactivated


The parameter allows you to specify a return url for a defined list of partners, for now: AmazonPay

When the buyer clicks on the AmazonPay button, he is redirected to the partner to authenticate. Once authenticated, it is redirected to the specified URL.

<div id="PaylineWidget"

According to the parameters, here are the examples of integration :

InShop Tab mode InShop Column mode LightBox mode Shortcut mode 

Payline forces column  page display  of payment pages when you use tab mode and the size of the device used by the consumer is too small to display properly. This enhancement simplifies your technical integration when you have a "responsive desktop / mobile" store.

Style sheet

To get the form of the payment form formatted, you have to integrate the CSS Payline style sheet by adding the following line in the <head> tag:

<link href="" rel="stylesheet" />

The URLs of the script and CSS are different between the test and production environments. We recommend that you configure them in environment variables.

JavaScript API

In order to interact with the payment form, Payline offers a JavaScript API to keep your hand on the form. The available functions of your IS are:


Ends the life of the web session token (token obtained via DoWebPayment).

Parameters  :
(  additionnalData : any,
  callback : Function,
  spinner : any,
  handledByMerchant : boolean )


Payline.Api.endToken(null, function() {
window.location.href = Payline.Api.getCancelAndReturnUrls().cancelUrl;
}, null, true);

// valuing handledByMerchant to true, 
// the payment session will be associated with return code 02014
// returned by getWebPaymentDetails.
// Otherwise the code 02319 is returned.
finalizeShortCut()Triggers the finalization of the payment ShortCut (to call in context.state PAYMENT_TRANSITIONAL_SHORTCUT)

Returns a complex object containing buyer data from the shortcut partner.

This function is available in a context of state = PAYMENT_TRANSITIONAL_SHORTCUT.

{  "firstName": "DUPONT",
  "lastName": "Jean",
   "email": "",
   "cityName": "Aix",
   "country": "FR",
   "street1": "5 rue de Marseille",
   "street2": "Batiment 2",
  "zipCode": "13390"
getCancelAndReturnUrls()Returns a complex object containing the returnUrl and the cancelUrl from the DoWebPayment
For example, you can create a cancel button that triggers the following actions:

function cancel() {
// end the token's life 

window.location.href =
// redirect the user to cancelUrl

getContextInfo(key)Returns a context information with its key from the following values:
{  "PaylineAmountSmallestUnit": 100,
  "PaylineCurrencyDigits": 2,
   "PaylineCurrencyCode": "EUR",
   "PaylineBuyerFirstName": "Jean",
   "PaylineBuyerLastName": "DUPONT",
   "PaylineBuyerShippingAddress.street2": "Batiment 2",
   "": "FR",
   "": "Perso",
   "PaylineBuyerShippingAddress.street1": "5 rue de Marseille",
   "PaylineBuyerShippingAddress.cityName": "Aix",
   "PaylineBuyerShippingAddress.zipCode": "13390"
   "PaylineBuyerMobilePhone": "0605040302",
"": "0605040302",
   "PaylineBuyerIp": "",
   "PaylineFormattedAmount": "EUR1.00",
   "PaylineOrderDate": "05/26/2008 10:00",
   "PaylineOrderRef": "170630111901",
   "PaylineOrderDeliveryMode": "4",
   "PaylineOrderDeliveryTime": "1",
   "PaylineOrderDetails": [
     { "ref": "1",
       "price": 998,
       "quantity": 1,
       "comment": "commentaire1",
       "category": "1",
       "brand": "66999",
       "subcategory1": "",
       "subcategory2": "",
       "additionalData": ""


Returns the list of accepted CSS primitives for stylizing protected fields (Credit Card, CVV, ...)

getCssIframeWhiteList(): any


In a context of fragmented payment (Carrefour Gift Card, soon ANCV, ...), allows to recover the various payments registered so far.



                "amount": "100,00 EUR", // Montant global de la commande
                "amountLeft": "50,00 EUR", // Montant restant à payer
                "recaps": [

                               503200XXXXXXXXX1166: "50,00 EUR"



getLanguage()Return the widget's language key (passed in the DoWebPayment frame)"en", "fr", …

Retrieves a complex object containing:

  • the amount with the currency all formatted
  • the order reference
  • the name of the point of sale
  • a complex object representing the address with:
    • address1
    • address 2
    • city
    • Postal code

We get :

Object {
   amountCurrency: "15.00 EUR"
   orderRef: "order-123456789"
   pointOfSale: "POS_Demo"
Object {
       addess1: "260 rue Claude Nicolas Ledoux"
       addess2: "ZI Les Milles"
       city: "Aix en Provence"
       zipCode: "13290" }}


Retrieves the payment schedule. 

See the integration details: payment N times and recurring payment.

To display the schedule N times:

Payline.Underscore.forEach( Payline.Api.getRecurringDetails().schedules, function(key, value) { console.log(value + " " + key) } );

To retrieve recurring payment details:



Returns the current token with which the Widget was initialized.

hide()Request to hide the payment form.
Payline.Api.hide(): void


Request to initialize the payment form. During initialization, the Payline widget builds the form according to the context of the payment request: amount, proposed payment method, etc.

isSandBox()Allows to know the environment: production or homologation. The function returns true or false.
reset()Totally reset the widget with the token and template passed as parameter.
Payline.Api.reset(token: string = null, template: string = null): void

show()Request to display the payment form. void
toggle()If the widget is displayed, this method hides it, otherwise it displays it.
updateWebpaymentData()Update of the payment session information (addresses, amount, ...) after the initialization of the widget and before the finalization of the payment.
Payline.Api.updateWebpaymentData(Payline.Api.getToken(), JSON, callBack);

Contents of the JSON:  
"payment": {
    "amount": "252",
    "currency": "978" },
    "amount": "255",
    "currency": "978",
    "ref": "123",
    "deliveryTime ": "1",
    "deliveryMode ": "1",
    "deliveryExpectedDate": "30/09/2016",
    "deliveryExpectedDelay": "1",
    "details": {

     [  { "ref": "00001 (ref1)",
          "price": "50",
         "quantity": "1",
         "comment": "comment1 (rem1)",
         "category": "1",
         "brand": "My HERMES (brd1)",
         "subcategory1": "BOSS",
         "subcategory2": "MONTRE",
         "additionalData": "LegalAge=18;Discount=0105",
         "taxRate ": "1234"
        { "ref": "00002 (ref2)",
          "price": "50",
          "quantity": "1",
          "comment": "comment2 (rem2)",
          "category": "1",
          "brand": "My HERMES (brd2)",
          "subcategory1": "HERMES",
          "subcategory2": "FOULARD",
          "additionalData": "LegalAge=18;Discount=0105",
          "taxRate ": "1234"
         { "ref": "00003 (ref3)",
         "price": "50",
         "quantity": "1",
         "comment": "comment3 (rem3)",
         "category": "1",
         "brand": "My HERMES (brd3)",
         "subcategory1": "HERMES",
         "subcategory2": "MONTRE",
         "additionalData": "LegalAge=19;Discount=0105",
         "taxRate ": "1234"
"buyer": {
"shippingAddress": {
"title": "2",
"name": "BUYER (shipping)",
"lastName": "PAYLINE (shipping)",
"firstName": "Validation Team (shipping)",
"street1": "Colombus Circle (shipping)",
"street2": "Central Park (shipping)",
"cityName": "New York (shipping)",
"zipCode": "NY 10023",
"country" : "FR",
"phone" : "0123458789",
"state": "NYC (state)",
"county": "Upper East Side (shipping)",
"phoneType": "1"
"billingAddress": {
"title": "3",
"name": "BUYER (billing)",
"lastName": "TUPU (billing)",
"firstName": "Christian (billing)",
"street1": "15 rue LEDOUX (billing)",
"street2": "Z.I. les Milles (billing)",
"cityName": "Aix-en-Provence (billing)",
"zipCode": "13902",
"country" : "FR",
"phone" : "0223458789",
"state": "FRANCE (state)",
"county": "Bouches-du-Rhone",
"phoneType": "4"

Example to hide and then display the payment form:

  • Payline.Api.hide (): void
  • (): void

Example to change the label on Pay button:

  • You can change it using the JavaScript statement Payline.jQuery ('. Pl-pay-btn'). Text (' button label ');

Example to change the label on Pay button:

  • You must recover the amount  in the language of the buyer via a call to the function Payline.Api.getContextInfo ('PaylineFormattedAmount');
  • You can change the text of the button with the function:  Payline.jQuery ("<class of the element to modify>"). Text ('<replacement text>'));

(warning)  Warning, always use the classes for these instructions, never the id of the element that is generated on the fly

  • To display the amount in the button. The statement is therefore Payline.jQuery (".paylineWidget .pl-pay-btn, .PaylineWidget .pl -btn"). Text ('Pay' + Payline.Api.getContextInfo ('PaylineFormattedAmount'));
  • This statement must be called when the widget triggers the " didshowstate " event with the PAYMENT_METHODS_LIST state .

CSS customization

Customizing the style of the payment form is possible by overloading the default style sheet provided by Payline. The possibilities of customization are endless, here are some simple examples:

The color of the banner Sign
#PaylineWidget .pl-header-title-wrapper { background-color: #ABCDEF; }
The color of the sign's text
#PaylineWidget .pl-header-title-content h4 { color: #ABCDEF; }
The color of the text of the amount to be paid
#PaylineWidget .pl-header-title-content p { color: #ABCDEF; }
The color of the payment button
#PaylineWidget .pl-pay-btn { background-color: #ABCDEF; }
#PaylineWidget .pl-pay-btn:hover { background-color: #ABCDEF; }
The background color of the form
#PaylineWidget .pl-body { background-color: #ABCDEF; }
The color of the area of ​​payment
#PaylineWidget .pl-pmContainer {
  background-color: #ABCDEF;
  border-color: #ABCDEF; }
The color of the button close the lightbox
#PaylineWidget .pl-icon-close { color: #ABCDEF; }

The size of the window is optimized in the following configuration:

  • minimum width of the div PaylineWidget: 500px
  • maximum recommended width of the PaylineWidget div: 900px

Below and above the indicated dimensions, it is recommended to adjust the margins and fields.

To hide the labels, you must remove the labels and delete the margin to the left of the fields. .pl-pmContainer .pl-label-input 
{ display: none;} .pl-pmContainer .pl-input-group-container
 { margin-left: 0; }

Payline proposes to reduce the margins in order to adjust the window above 900px wide, for that it is enough to decrease the width of the label (xx%), and to decrease the margin to the left of the fields (yy% by default 30% ). .pl-pmContainer .pl-label-input
{ width: xx%; } .pl-pmContainer .pl-input-group-container, .pl-form-container
{ margin-lef: yy%; }

For more information on the list of tags, find the information here.

Life cycle callback

Error rendering macro 'excerpt-include'

No link could be created for 'PW - Customizing the widget: CallBack function'.

Features Fee Management

The expense management is present on the payment form and corresponds to the Transaction insert:

Back office : Configure the payment methodBack office : transaction detailsPayment page

Fee management excludes in the following cases:

  • Wallet Payment
  • ShortCut Payment
  • Payment Rec / NX