ecard-plugin-doc

Pledg

eCard Plugin Integration Documentation

Table of contents

Principle

The Pledg plugin generates an eCard, i.e. a debit bank card with the amount of the purchase, and triggers the payment with these eCard infos.

The JavaScript code of the frontend page just has to call the plugin, initialized with:

The plugin can be used in two different modes:

The differences between the 2 modes are summarized in the table below:

Mode front back
Integration Merchant frontend Merchant frontend
Entity completing the payment Merchant backend Pledg backend
Parameter passed by the plugin to the callback eCard infos Payment result returned by the PSP
Scope of the callback Fill the already existing payment form with the ecard infos and submit it to the already existing payment page of the merchant backend Optionally, submit the payment result to the merchant backend

User workflow

  1. The user clicks on the Pledg payment button, which opens the Pledg payment funnel inside an iframe

  2. The user fills his email and those of his friends

  3. The user fills out his card details

  4. The Pledg server makes an authorisation (via Stripe) for the total amount of the purchase. For security purposes, Pledg does not store the user’s card details. It only stores a reference to the card in order to make the payment later.

  5. The Pledg server generates an eCard credited with the total amount of the purchase

  6. [back mode only] The Pledg server submits the eCard to the merchant PSP for payment, via the PSP API.

  7. The Pledg server sends a validation email to the user and invitation emails to his friends

  8. [front mode only] The merchant front submits the eCard to the merchant server for payment, as if it was a standard card. The details of the generated eCard are not visible for the user and are directly handled by the plugin.

  9. The user lands on the merchant payment confirmation page.

How to integrate the plugin

Pledg database

To integrate a merchant in its platform, Pledg creates a merchant entity in its database, with the following parameters:

name description usage
name Name of the merchant To fill the emails
uid Unique identifier of the merchant To instantiate the plugin
site_url URL of web site of the merchant To fill the emails
picture_url URL of the logo of the merchant To fill the mails
css_url URL of the iframe CSS To customize the layout of the payment funnel
cgu_url URL of the general terms of use (GTU) of the merchant To customize the layout of the payment funnel
cgu_message Label of the link to the GTU of the merchant To customize the layout of the payment funnel
auth_direct If true, the 3DS is never used To simplify the user journey
psp_connector Connection parameters to the merchant PSP To use the plugin in back mode - see Details on the back mode
timezone Timezone (Europe/Paris by default) To localize the date and time in the emails
leader_can_pay_alone If true, Pledg is used even if the user did not specify any friend (true by default)  
purchase_end_notification_url URL to notify the merchant of the end of the purchase shared payment See Notifications

HTML


<body>

...

<!-- form to submit the eCard infos - 'front' mode only -->
<form id="form" method="post" action="your-payment-triggering-server-side-code">
    <input type="text" id="card-number" name="card-number">
    <input type="text" id="card-expiry-month" name="card-expiry-month">
    <input type="text" id="card-expiry-year" name="card-expiry-year">
    <input type="text" id="card-cvc" name="card-cvc">
</form>

<!-- button to open the Pledg payment funnel -->
<button id="pledg-button" type="button">Pay with friends</button>

<!-- Optional - We mention it only to illustrate the 'configure' method of the plugin -->
<input type="text" name="customer-email" id="customer-email" value="sales@pledg.co">

...

<!-- This script contains the code of the plugin -->
<script src="https://s3-eu-west-1.amazonaws.com/pledg-assets/ecard-plugin/BRANCH/plugin.min.js"></script>

<!-- This script contains the call to the plugin
     See the 'Javascript' section below -->
<script type="text/javascript">
...
</script>

</body>

BRANCH 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, {
    // the Pledg merchant id
    merchantId: 'mer_uid',
    // the amount **in cents** of the purchase
    amountCents: 6500,
    // the email of the customer (optional - here, it is retrieved from a control on the page)
    email: document.querySelector('#customer-email').value,
    // reference of the purchase
    reference: 'order_123',
    // the name of the customer (optional, to improve anti-fraud)
    first_name: 'Eric',
    last_name: 'Tabarly',
    // the shipping address (optional, to improve anti-fraud)
    address: {
        street: '2 pointe de kervigorn',
        city: 'saint pabu',
        zipcode: '29830',
        state_province: 'Bretagne',
        country: 'France'
     },
    // the function which triggers the payment
    onSuccess: function (eCard) {
        document.querySelector('#card-number').value = eCard.card_number
        document.querySelector('#card-expiry-month').value = eCard.expiry_month
        document.querySelector('#card-expiry-year').value = eCard.expiry_year
        document.querySelector('#card-cvc').value = eCard.cvc
        document.querySelector('#form').submit()
    },
    // the function which can be used to handle the errors from the eCard
    onError: function (error) {
        // see the "Errors" section for more a detailed explanation
    },
})

// The code below illustrates how the plugin can be reconfigured after its creation.
// Here, when the focus leaves the control #customer-email, the new email is
// set in the configuration of the plugin.
// All the parameters of the plugin can be reconfigured dynamically using the
// 'configure' method.
document.querySelector('#customer-email').addEventListener('blur', function(e) {
            pledgInstance.configure({
                email: document.querySelector('#customer-email').value
            })
        })
</script>

Under the hood, the plugin sets a JavaScript listener to catch (and then handle) the eCard generated by the Pledg iframe.

The eCard is generated within the Pledg iframe and sent to the plugin using the standard browser API Window.postMessage.

Important notes:

CSS (optional)

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);
}

The merchant can customize the layout of the funnel with the CSS specified in the database. This CSS is retrieved by the iframe and applied to its content.

An example of CSS is provided there.

Settings

As illustrated above, the Pledg button must be instantiated like this: new Pledg(button, settings).

The settings are passed as the second argument of the Pledg class.

All available settings, required and optional, are detailed below.

Required settings

name type details
amountCents integer Amount in cents to be credited on the eCard. The maximum value is currently 1000000.
merchantUid string Your merchant id
reference string Reference of the purchase in the system of the merchant
onSuccess function Function which triggers the payment with the eCard infos; takes the generated eCard as first argument

Optional settings

name type details
email string Email of the client (if not set, it must be set by the user in the Pledg funnel)
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)
onClose function Function to call when the iframe is closed (typically to hide/display some DOM elements)
onCancel function Function to call when the user closes himself the iframe without completing the payment
title string Title of the purchase
subtitle string Subtitle of the purchase
iframeBaseUrl string URL of the iframe (https://front.ecard.pledg.co by default)
currency string Currency of the amount (EUR by default - only EUR, GBP and CZK are supported)
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).
singlePage boolean If true, the different steps of the funnel are displayed on a single page (false by default)
products [{label: string, priceCents: integer}] List of the products purchased by the client. The sum of priceCents for all the products must be equal to amountCents. If set, the client assigns a subset of the products to each participant, instead of assigning an amount.
lang string Language to be used (fr_FR or en_GB only - fr_FR by default)
first_name string Customer first name
last_name string Customer last name
address {street: string, city: string, state_province: string, zipcode: string, country: string} Customer shipping address
pspAuthorizationId string Authorisation ID provided by the PSP (see Details on the postpayment)
confirm string The user is asked a confirmation before entering the funnel

Errors handling

An error is an object containing two properties: type and message, for instance:

{
    type: 'invalid_request_error',
    message: 'The provided property email is invalid'
}

Errors are all handled in the onError function:

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

    onError: function (error) {
        if (error.type === 'payment_refused') {
            // Handle payment_refused errors here
        } else if (error.type === 'invalid_request_error') {
            // Handle invalid_request_error errors here
        } else if (error.type === 'internal_error') {
            // Handle internal_error errors here
        }
    },
})

The different values for error.type are the following:

name cause
invalid_request_error Your settings are malformed (ex.: invalid merchandId, invalid email, invalid amountCents, …)
internal_error The Pledg server failed
maintenance The Pledg server is under maintenance
payment_refused The PSP of Pledg failed
bad_gateway The PSP of the merchant failed (back mode only)
3DS_confirmation_timeout The 3DS payment process could not be completed on time
direct_confirmation_timeout The direct (i.e. without 3DS) payment process could not be completed on time

When an error is raised, the iframe is always closed.

If a payment is rejected by the PSP for any reason (3DS failed, insufficient funds, etc.), an error message is displayed to the user inside the iframe, but no error is raised by the plugin. Indeed, in such as situation, the user keeps the possibility to retry with another card.

Tests

To test the integration on the staging platform:

Note: the eCards generated with the staging platform of Pledg can be used to test the payment process on the site of the merchant. Nevertheless, the payment will ultimately be rejected by the bank, as if the account was not provisioned.

Examples

Many examples of integration are available online.

The easiest way to integrate the plugin is to copy/paste the code of the most relevant example and to adapt it to your particuliar needs.

Tag manager

The code of the plugin and the code to instantiate the plugin can be loaded by a tag manager.

An example of integration with Google Tag Manager (GTM) is available there.

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 section above. 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/BRANCH/plugin.min.js"></script>

<script type="text/javascript">

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

new Pledg(button, {
    // the Pledg merchant id
    merchantId: 'mer_uid',
    title: ,
    subtitle: ,
    email: document.querySelector('#customer-email').value,
    amountCents: ,
    reference: ,
    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': 'Votre séjour à Londres',
        'subtitle': 'Vol + Hôtel 2 nuits (2 adultes)',
        'amountCents': 30550,
        'reference': 'order_123',
        'currency': 'EUR'
    })
    // Trigger the tag once dataLayer variables are set
    dataLayer.push({
        'event': 'loadPledgTag'
    })
</script>

Notifications

The merchant can define a webhook to be notified of the end of the shared payment of the purchase.

This webhook is sent when all friends have paid their share or, at the latest, at the end of a period of 48 hours after the purchase

This webhook is a POST which body contains the merchant reference of the purchase and the Pledg uid the purchase:

POST /merchant_webhook_purchase_end
{'reference': 'merchant_purchase_reference', 'uid': 'pledg_purchase_uid'}

This webhook is provided only for information, without any error managment or retry.

Details on the back mode

Your can find an example of each back mode integrations in the section back mode at the bottom of the demos Pledg Demo.

For each one, you need to send your psp parameters to Pledg so we can configure the connection.

Adyen

Parameters

description example
URL of the payment endpoint https://pal-test.adyen.com/pal/servlet/Payment/v40/authorise
User of the Adyen merchant account  
Password of the Adyen merchant account  
Account name of the Adyen merchant account  

Structure of the payment result

The structure of the payment result is documented in the doc of Adyen itself.

SystemPay

Parameters

description example
Shop id  
Production Certificate  

Structure of the payment result

The structure of the payment result is

{'transaction': {'created_at': '2018-12-10T16:12:36.122775Z',
                 'error': None,
                 'id': 'psp_id',
                 'sandbox': False,
                 'status': 'completed'}}

The id is the true PSP id (for example Stripe), not the Pledg id. It can be retrieved in the PSP dashboard.

The transaction statuses are documented there.

Details on the postpayment

The postpayment is an adaptation of the standard usage of the ecard plugin, based on the following assumptions:

The user workflow is the following:

  1. The user fills out his card details
  2. The user clicks on the unique payment button
  3. The merchant front sends an authorisation request for the total amount of the purchase to the PSP and retrieves the authorisation ID
  4. The merchant front calls the plugin with this authorisation ID, which opens the Pledg payment funnel inside an iframe
  5. If the plugin returns an error, or if the user decides not to share the payment, the authorisation is immediately captured
  6. Otherwise, if the user decides to share the payment:
    • The Pledg server generates an eCard credited with the total amount of the purchase
    • The Pledg server submits the eCard to the merchant PSP for payment, via the PSP API
    • The Pledg server sends a validation email to the user and invitation emails to his friends
  7. The user lands on the merchant payment confirmation page.

The specificities of the integration are the following:

A demo is available there.