ecard-plugin-doc

Pledg

eCard Plugin Integration Documentation

Table of contents

Principle

The eCard plugin developped by Pledg is a Javascript plugin allowing any web merchant to propose the payment sharing feature to its customers.

In most cases, the plugin generates an eCard, i.e. a debit bank card provisioned with the amount of the purchase, and completes the payment with it.

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

The plugin can be used in 4 different modes:

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

  Front mode Back mode with immediate payment Back mode with delayed payment Postpayment mode
Integration for the merchant Frontend Frontend Frontend and PSP Frontend, backend and PSP
Backend completing the payment Merchant Pledg Pledg Merchant and Pledg
Card used to pay the merchant eCard eCard Customer card Customer card or eCard
Result returned by the plugin eCard infos Payment result returned by the PSP of the merchant Preauthorisation result returned by the PSP of the merchant Preauthorisation Id returned by the PSP of the merchant
Scope of the JS callback Submit for debit the ecard infos to the merchant backend Submit for info the payment result to the merchant backend Submit for info the preauthorisation result to the merchant backend Submit for capture the preauthorisation Id the merchant backend

Plugin integration

Merchant parameters

When Pledg integrates a merchant in its platform, it assigns a unique merchantId to this merchant.

The merchant can also communicate to Pledg the values to be assigned to the configuration parameters below, in order to customize the user experience.

Name Description Usage
Name Name of the merchant (mandatory) To fill the emails/SMS
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
GTU URL URL of the general terms of use (GTU) of the merchant To customize the layout of the payment funnel
GTU message Label of the link to the GTU of the merchant To customize the layout of the payment funnel
Direct authentication If true, the 3DS is never used To simplify the user journey
PSP connnector Connection parameters to the merchant PSP To use the plugin in back mode with immediate payment or in postpayment mode
PSP interface Connection parameters to the merchant PSP To use the plugin in back mode with delayed payment
Timezone Timezone (Europe/Paris by default) To localize the date and time in the emails/SMS
Leader can pay alone If true, the shared payment mechanism 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)

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.

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

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.
merchantId string Your merchant id
reference string Reference of the purchase in the system of the merchant
title string Title of the purchase
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
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 Postpayment mode)
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 backend failed
maintenance The Pledg backend 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 (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:

The specificities of the integration of a particular mode are detailed in the Integration section of the mode in this document.

Demos

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.

Discounts

The merchant can apply a discount on the purchases made with Pledg.

There is at most one active discount per merchant.

If there is an active discount, it is applied to all the purchases of the merchant.

To create the discount, the merchant must communicate to Pledg the following informations:

Specificities of the different modes

Front mode

Use case

This mode should be used when the card payment form is a plain form (i.e. not an iframe) hosted on the merchant’s payment page. In this case, the eCard information can be directly passed to the card payment form on the merchant frontend.

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 the emails or phone numbers of his friends
  3. The user fills out his card details
  4. The Pledg backend completes a preauthorisation on the user bank account, for the total amount of the purchase, to the credit of the Pledg bank account. 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 backend generates an eCard credited with the total amount of the purchase
  6. The plugin returns the details of the eCard
  7. The merchant frontend submits the eCard to the merchant backend for payment, as if it was a standard card.
  8. The user lands on the merchant payment confirmation page
  9. The Pledg backend sends an email to the user and an email or an SMS to his friends

Integration

This mode is particularly simple to deploy as there is strictly no configuration to be completed on the merchant backend or merchant PSP.

In staging, it may be necessary to replace, in the function onSuccess, the eCard returned by the plugin by one the tests cards expected by the PSP of the merchant in its testing environment (see Stripe or Adyen, for instance). An example of such a replacement is provided in the source code of the Stripe demo.

For the specific case of a payment page using the Stripe form:

Result

The result is for example:

{'card_number': '5000056655665557',
 'expiry_month': '06',
 'expiry_year': '2018',
 'cvc': '897'}

Demo

A demo in a classic payment page is available there.

Other demos, in a payment page using the Stripe payment form, are available: one using a token and another one using a source.

Back mode with immediate payment

Use case

This mode should be used when :

  1. The payment page is hosted by the merchant’s Payment Service Provider or
  2. The payment form is integrated on an iframe on the merchant’s payment page This is the case when the eCard information cannot be directly passed to the card payment form on the merchant frontend.

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 the emails or phone numbers of his friends
  3. The user fills out his card details
  4. The Pledg backend completes a preauthorisation on the user bank account, for the total amount of the purchase, to the credit of the Pledg bank account. 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 backend generates an eCard credited with the total amount of the purchase
  6. The Pledg backend submits the eCard to the merchant PSP for payment, via the PSP API
  7. The plugin returns the result of the payment
  8. The merchant frontend submits the result of the payment to the merchant backend
  9. The user lands on the merchant payment confirmation page
  10. The Pledg backend sends an email to the user and an email or an SMS to his friends

Integration

SystemPay / PayZen

When the PSP of the merchant is SystemPay or Payzen, the merchant must provide to Pledg the following parameters:

description example
Shop id  
Production Certificate  
Ogone

When the PSP of the merchant is Ogone , the merchant must provide to Pledg the following parameters:

description example
Login  
Api User  
Api Password  
Signature  

Login is the global account. To more infos about the Api User please see :

Standard Result

The structure of the payment result (which is independent of the merchant PSP) 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.

Payzen Result

The structure of the payment result is:

{'transaction': {'created_at': '2018-12-10T16:12:36.122775Z',
                 'error': None,
                 'id': 'payzen_transaction_id', # ex 9xxxx7
                 'uid': 'payzen_transaction_uid',  # ex a717ae49e2844cb19ef19a702dc1xxxx
                 'sandbox': False,
                 'status': 'payzen_status_label'}}  # always AUTHORISED

The Payzen web service createPayment called by the back returns in paymentresponse the transaction id and uid :

For more information, see there.

paymentResponse also contains the values responseCode and transactionStatusLabel.

If responseCode is different from 0, the plugin calls the onError callback.

If transactionStatusLabel is different from AUTHORISED, the plugin calls the onError callback.

In the result above, status contains the transactionStatusLabel value, i.e. AUTHORISED.

For more information, see there.

Demo

A demo is available there.

Back mode with delayed payment

Use case

This mode should be used when the merchant wants to use its own Payment Service Provider to collect the payments of the participants. Note that in this case, the merchant is not paid instantly when the order is placed, but after the 48-hour payback delay at the latest.

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 the emails or phone numbers of his friends
  3. The user fills out his card details
  4. The Pledg backend completes a preauthorisation on the user bank account, for the total amount of the purchase, to the credit of the merchant bank account. 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 backend submits the user’s card to the merchant PSP for payment, via the PSP API
  6. The plugin returns the result of the preauthorisation
  7. The merchant frontend submits the result of the preauthorisation to the merchant backend
  8. The user lands on the merchant payment confirmation page
  9. The Pledg backend sends an email to the user and an email or an SMS to his friends

Integration

Stripe

When the PSP of the merchant is Stripe, the merchant must provide to Pledg the following parameters:

description example
Stripe test public key pk_test_xx
Stripe test private key sk_test_xx
Stripe prod public key pk_xx
Stripe prod private key sk_xx

The merchant must also define some webhooks, so that Pledg can manage the payment workflow.

These webhooks must be configured in the dashboard of the merchant, on the Stripe back-office

These webhooks are the following (where merchantUid is the value detailed in Required settings:

type url events
source https://staging.back.ecard.pledg.co/api/event/stripe/source/merchantUid source.chargeable, source.failed
charge https://staging.back.ecard.pledg.co/api/event/stripe/charge/merchantUid charge.expired, charge.failed, charge.succeeded

It is important to select only the events listed in the table above, in order to avoid sending all the events to Pledg.

Result

The structure of the payment result (which is independent of the merchant PSP) is:

{'transaction': {'id': 'ch_xx'},
 'purchase': {'id': 'pur_xx',
              'reference': 'order_123'}}

In this example:

Demo

A demo is available there.

Postpayment mode

Use case

This mode should be used when the merchant wants the user to provide his credit card information before proposing him to share the payment.

It is available only if the PSP of the merchant is Adyen.

When the payment is shared between the leader and his friends, 2 cards are used for the same purchase:

Workflow

  1. The user fills out his card details
  2. The user clicks on the unique payment button
  3. The merchant frontend sends an authorisation request for the total amount of the purchase to the PSP and retrieves the authorisation ID
  4. The merchant frontend 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 backend generates an eCard credited with the total amount of the purchase
    • The Pledg backend submits the eCard to the merchant PSP for payment, via the PSP API
    • The plugin returns the result of the payment
    • The merchant frontend submits the result of the payment to the merchant backend
    • The Pledg backend sends an email to the user and an email or an SMS to his friends
  7. The user lands on the merchant payment confirmation page.

Integration

The merchant must provide to Pledg the credentials of its Adyen account:

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  

On its frontend payment page, the merchant must capture:

On its backend and in the settings of its PSP, the merchant must make sure that the capture is delayed, i.e. that there is an authorisation request first, and then a capture request.

Result

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

It is for example:

{'pspReference': '8535465143188715',
 'resultCode': 'Authorised',
 'authCode': '79957'}

Demo

A demo is available there.