Integration of the Pledg payment solution

# By plugin

# Use case

If the Pledg funnel can be integrated within an iframe inside the merchant payment page, the merchant should use the plugin provided by Pledg to that aim. This integration provides the best UX to the customer.

# Settings

This section lists the settings specific to the integration by plugin, none of them being used for the scoring.

The other settings are detailed in the settings section.

# Required settings

Name Type Details
onSuccess function Function which handles the result

# Optional settings

Name Type Details
configure function Function receiving an object as parameter, to reinitialize the settings of the plugin
containerElement element DOM element which must contain the iframe (if not set, the iframe is displayed as a popin). It is strongly recommended to use a container and not a popin. Indeed, iOS does not support very well the large iframe in popins. Technically, if the popin is larger than the viewport, the window scrolls down automatically. This is a problem when creating the shares, since the user cannot see what he is typing. If it is absolutely necessary to use a popin, the plugin can be hidden for iOS devices (see an exemple of code there (opens new window)).
externalCheckoutValidation boolean Indicates whether validation button is displayed by the merchant or not (false by default).
onCancel function Function to call when the user closes himself the iframe without completing the payment
onCheckoutFormStatusChange boolean Function with parameter boolean readiness to inform the merchant when validation button shall be greyed out (externalCheckoutValidation set to true).
onCheckValidity function Function that should handle the validity of the data
onPaymentSolutionsAccess function Function that should handle the access to the payment solutions page
onClose function Function to call when the iframe is closed (typically to hide/display some DOM elements)
onError function Function that should handle and display potential errors
onOpen function Function to call when the iframe is opened (typically to hide/display some DOM elements)
onSetback function Function that should handle setbacks
validateCheckout function Function to call to validate payment form when validation button is handled by merchant (externalCheckoutValidation set to true).

# onCheckValidity

The onCheckValidity function is called

  • when the payment has been created without error
  • when an error occured while creating the payment (will not prevent the onError callback from firing)
new Pledg(button, {
    // ... Other settings merchantUid, amountCents, ...

    onCheckValidity: function ({ isValid, error }) {
        if (isValid) {
            // Ex: display payment button
        } else {
            // See Errors section
        }
    },
})

# onPaymentSolutionsAccess

The onPaymentSolutionsAccess function is called

  • when the user has been redirected to the payment solutions page without error
  • when an error occured while attempting to access the payment solutions of a given company
new Pledg(button, {
    // ... Other settings companyUid, amountCents, ...

    onPaymentSolutionsAccess: function ({ isValid, error }) {
        if (isValid) {
            // Everything is fine
        } else {
            // Cannot access the payment solutions page
        }
    },
})

# onSetback

Some errors are not critical and will not close the payment funnel. Setbacks usage allows you to have some insights.

Setbacks are handled in the onSetback function (optionnal).
This callback provide an object containing two properties: type and debug, for instance:

{
    type: "checkout_completion_failure",
    debug: "Your card has been declined. Try another card."
}

new Pledg(button, {
    // ... Other settings merchantUid, amountCents, ...

    onSetback: function (payload) {
        if (payload.type === "checkout_completion_failure") {
            // Checkout failed: unauthorized card type, insufficient funds, iban is not valid ...
        } else if (payload.type === "otp_validation_failure") {
            // One time password sent by phone could not be verified
        },
        // ...
    },
})

The different values for payload.type are the following:

Name Cause
checkout_completion_failure The user checkout has failed (insufficient funds, invalid card, [...]), the user is invited to retry or change payment method
otp_validation_failure Some payments requires a phone number verification, either validation code is wrong or service is not available for this phone number.
split_validation_failure For split payment, user entered a wrong or duplicated email, phone

Important notes:

  • This list is exhaustive but will be updated.
  • The use of setbacks does not replace error handling, it is optional.

# Merchant frontend

# From the merchant frontend

The merchant must instantiate the Pledg plugin with the settings on its payment page and link it to a clickable component.

When the user clicks on the component, the payment funnel is displayed, either embedded in the page or in a popin.

If the parameters are signed, a unique parameter signature is passed to the plugin.

When the iframe is displayed in a popin, the merchant can customize its overlay by applying a style to the class .pledg-iframe-overlay in the CSS used by the page containing the Pledg button:

.pledg-iframe-overlay {
    background: rgba(255, 255, 255, 0.3);
}

# Back to the merchant frontend

In case of success, the callback onSuccess is called with result passed as parameter, where result is the result returned by the solution.

In case of error, the callback onError is called with error passed as parameter, where error is the error returned by the solution.

If the error is an initialization error, it may be worth that the onError callback hides the Pledg component. Indeed, such an error implies that the Pledg component is not usable in this context. It is recommended that the onError callback does not redirect to an error page, since this error may occur even if the user does not click on the Pledg button.

If the error is a payment error, it may be worth to display an error message or to redirect to an error page.

# Code sample

# HTML

<body>
...
<!-- The button to open the Pledg funnel -->
<button id="pledg-button" type="button">Pay in installments</button>
<!-- The container of the Pledg funnel -->
<div id="pledg-funnel-container"></div>
...
<!-- This script contains the code of the plugin -->
<script src="https://s3-eu-west-1.amazonaws.com/pledg-assets/ecard-plugin/<ENV>/plugin.min.js"></script>
<!-- This script contains the call to the plugin - See the "Javascript" section below -->
<script type="text/javascript">
...
</script>
</body>

ENV must be equal to master on the production platform, and to staging on the staging platform.

# JavaScript

<script type="text/javascript">

var button = document.querySelector("#pledg-button")

new Pledg(button, {
    merchantUid: "mer_uid",
    amountCents: 30550,
    email: "[email protected]",
    title: "STAY IN LONDON",
    subtitle: "Fly + Hotel 2 nights (3 rooms)",
    reference: "order_123",
    firstName: "Gaëlle",
    lastName: "Guéguen",
    metadata : {"departure-date": "2022-03-30"},

    // Parameters below are specific to the integration by plugin

    containerElement: document.querySelector("#pledg-funnel-container"),
    // Function handling the result
    onSuccess: function (result) {
        // back mode: see integration/payment_modes/back_mode.html#result
        // transfer mode: see integration/payment_modes/transfer_mode.html#result
       ...
    },
    // Function handling the errors
    onError: function (error) {
       // see integration/principles/result.html#error
       ...
    },
})

</script>

Important notes:

  • The <script>...</script> sections must be located at the bottom of the page, i.e. just before </body>, so that the loading of the scripts does not slow down the display of the page
  • The script containing the call to the plugin must be loaded together with the page, and not later, when the user clicks on the button, for 2 reasons:
    • For performance reasons, it is better to initialize the plugin as soon as possible
    • The plugin manages by itself the binding of the click event on the button with the opening of the funnel
  • The plugin must be instantiated only once, i.e. new Pledg(...) must be called only once

# Demos

Examples of integrations by plugin are available in back mode (opens new window), transfer mode (opens new window).

# Tag manager

The code of the plugin and the code to instantiate the plugin can be loaded by a tag manager. Be aware that tag manager is likely to be blocked by content blockers (ads, tracking). Including this script may then cause issues if the tag manager does not load properly.

The configuration for GTM is the following:

  1. Create a tag in the Google Tag Manager interface. This tag has a GTM_ID and contains a piece of HTML/Javascript code to be injected in the payment page.

  2. Set in the tag the code detailed in the JavaScript plugin section. The only difference is that the parameters passed to the plugin are the attributes of the dataLayer structure (see the following step).

<script src="https://s3-eu-west-1.amazonaws.com/pledg-assets/ecard-plugin/<ENV>/plugin.min.js"></script>

<script type="text/javascript">

var button = document.querySelector("#pledg-button")

new Pledg(button, {
    // the Pledg merchant id
    merchantUid: "mer_uid",
    title: {{dataLayer - title}},
    subtitle: {{dataLayer - subtitle}},
    email: document.querySelector("#customer-email").value,
    amountCents: {{dataLayer - amountCents}},
    reference: {{dataLayer- reference}},
    currency: {{dataLayer - currency}},
    ...
})
...
</script>

  1. At the beginning of the head and body sections of the HTML payment page, add the scripts provided by the Google Tag Manager (see the section Install Google Tag Manager in the Google Tag Manager administration interface)

  2. At the bottom of the HTML payment page, set the dataLayer variables and trigger the event to load the tag

<script type="text/javascript">
    // Set the variables
    dataLayer.push({
        "title": "STAY IN LONDON",
        "subtitle": "Fly + Hotel 2 nights (3 rooms)",
        "amountCents": 30550,
        "reference": "order_123",
        "currency": "EUR"
    })
    // Trigger the tag once dataLayer variables are set
    dataLayer.push({
        "event": "loadPledgTag"
    })
</script>

← By redirection →