# Settings

The settings used in all integration modes are detailed below.

The settings specific to the integration by plugin are detailed there.

The settings specific to the integration by redirection are detailed there.

# 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
email string Email of the client
firstName string First name of the client
lastName string Last name of the client
reference string Unique reference of the purchase in the system of the merchant (note: if the merchant calls the solution with a given reference and if the purchase is successfully completed, the merchant cannot call the solution with the same reference anymore)
title string Title of the purchase

# B2B settings

The following settings are also required for b2b transactions.

Name Type Details
b2bCompanyName string Client company name (FR: raison sociale de l'entreprise acheteur)
b2bCompanyNationalId string Unique ID in the French company registry (.i.e: SIREN code)

# Contractual settings

The settings below can be required or optional, depending on the configuration of the merchant defined contractually.

Name Type Details Scoring
metadata Object Merchant-specific data (typically, a tour operator may set {"departure_date": "2019-02-01"} in this field) Used
phoneNumber string Customer phone number (E164) Used
address {street: string, city: string, stateProvince: string, zipcode: string, country: string} Customer billing address

The country must be an ISO 3166-1 alpha-2 code

country must be equal to FR for installment and deferred payments

If the street is split on several lines (e.g. "line1" and "line2"), it is recommended to join them in a single string with a comma (i.e. "line1, line2")
Used
birthDate string Customer birth date (YYYY-MM-DD) Used
birthCity string Customer birth city Used
birthCountry string Customer birth country (ISO 3166-1 alpha-2 code) Used

# Optional settings

Name Type Details Scoring
subtitle string Subtitle of the purchase (use \| as line separator) Not Used
currency string Currency of the amount (EUR by default - only EUR and GBP are supported) Not Used
lang string Language to be used (de_DE, en_GB, es_ES, fr_FR, it_IT, nl_NL and pt_PT only - fr_FR by default) Not Used
paymentNotificationUrl string Merchant URL (https://www.example.com) or email address (mailto:john.doe@gmail.com) to call at the payment end Not Used
errorNotificationUrl string Merchant URL (https://www.example.com) to call when the purchase fails after the payment screen Not Used
countryCode string Can be used to override merchant Country code settings for a purchase Not Used
balancePaymentDate string Date of payment of the balance (YYYY-MM-DD). Only for DOWN_PAYMENT payments. The latest possible date of balance payment is always today + the delay in days specified in the configuration. If balancePaymentDate is set, it is the balance payment date, and it must be before the latest possible one. If balancePaymentDate is not set, the balance payment date is the latest possible one. Not Used
deferredPaymentDate string Date of deferred payment (YYYY-MM-DD). Only for DEFERRED payments. The latest possible date of deferred payment is always today + the delay in days specified in the configuration. If deferredPaymentDate is set, it is the deferred payment date, and it must be before the latest possible one. If deferredPaymentDate is not set, the deferred payment date is the latest possible one. Not Used
secondInstallmentPaymentDate string Date of the second installment (YYYY-MM-DD). Only for INSTALLMENT payments with 5 or more installments. Delays the second installment at the specified date. All the following shares will start from secondInstallmentPaymentDate and be monthly separated. See details below. Not Used
signature string Signature of all the parameters except, of course, the signature itself (see Signature). Not Used
showCloseButton boolean Indicates whether the red cross on the upper right corner should be displayed (true by default). Not Used
civility string Customer civility (Mr or Ms) Used
shippingAddress {street: string, city: string, stateProvince: string, zipcode: string, country: string} Customer shipping address

The country must be an ISO 3166-1 alpha-2 code

country must be equal to FR for installment and deferred payments

If the street is split on several lines (e.g. "line1" and "line2"), it is recommended to join them in a single string with a comma (i.e. "line1, line2")
Used
birthZipcode string Customer birth zip code Used
birthStateProvince string Customer birth region Used

# How to delay the second share expiration date for installment payments?

If secondInstallmentPaymentDate is lower than payment created date we do not consider secondInstallmentPaymentDate value.

For regulation purpose, the funding duration cannot exceed 12 months. Thus, if secondInstallmentPaymentDate is too far from created date, we aggregate the exceeding installments into one (see example below).

Examples:

  • A 5 installments payment of 500€ created on 2020-01-01 with no secondInstallmentPaymentDate:

    • 1st share: 100€, due the 2020-01-01
    • 2nd share: 100€, due the 2020-02-01
    • 3rd share: 100€, due the 2020-03-01
    • 4th share: 100€, due the 2020-04-01
    • 5th share: 100€, due the 2020-05-01
  • A 5 installments payment of 500€ created on 2020-01-01 with secondInstallmentPaymentDate = "2020-05-15":

    • 1st share: 100€, due the 2020-01-01
    • 2nd share: 100€, due the 2020-05-15
    • 3rd share: 100€, due the 2020-06-15
    • 4th share: 100€, due the 2020-07-15
    • 5th share: 100€, due the 2020-08-15
  • A 5 installments payment of 500€ created on 2020-01-01 with secondInstallmentPaymentDate = "2020-11-15":

    • 1st share: 100€, due the 2020-01-01
    • 2nd share: 100€, due the 2020-11-15
    • 3rd share: 300€, due the 2020-12-15

# Metadata

In addition to the parameters described in the previous section, the field metadata contains a JSON with:

  • scoring data about the session
  • scoring data about the account
  • vertical-specific scoring data

The names of the fields are in lower case and in underscore case.

The fields with a name ending with _date represent a date, expressed as specified in ISO 8601 (opens new window) (i.e. with the format YYYY-MM-DD).

The fields with a name ending with country represent a country, expressed as Alpha-2 code as specified in ISO 3166-1 (opens new window) (i.e. FR for France).

The scoring data has the following structure :

  • Scoring data about the session :

The possible values for the field session.channel are the following: desktop, mobile, call_center, point_of_sale.

{
    "session": {
        "duration_seconds": 4612,
        "channel":  "desktop"
    }
}
  • Scoring data about the account :
{
    "account": {
        "creation_date": "2019-06-14", 
        "number_of_purchases": 14
    }
}
  • Vertical-specific scoring data :
    • Travel merchants : The possible values for the field travellers.document.type are the following: passport, visa, identity, driver_licence.

      The fields with a name ending with _airport are IATA airport codes (opens new window). These fields also support IATA railway station codes (opens new window).

      Example 1 : Paris -> Milano then Milano -> Paris (Return Flight)

      {
          "travel": {
              "number_of_travellers": 3,
              "departure_date": "2019-06-14",
              "departure_city": "Paris",
              "departure_airport": "CDG",
              "departure_country": "FR",
              "return_date": "2019-06-30",
              "destination_city": "Milano",
              "destination_airport": "MXP",
              "destination_country": "IT",
              "buy_date": "2019-05-10",
              "insurance": true
          },
          "travellers": [{
                  "id": "xxx1",
                  "buyer": true,
                  "birth_date": "1980-01-21",
                  "document": {
                      "type": "passport",
                      "validity_date": "2020-02-18",
                      "country": "FR"
                  }
              },
              {
                  "id": "xxx2",
                  "buyer": false,
                  "birth_date": "1982-03-17",
                  "document": {
                      "type": "passport",
                      "validity_date": "2021-10-18",
                      "country": "ES"
                  }
              },
              {
                  "id": "xxx3",
                  "buyer": false,
                  "birth_date": "2019-03-15"
              }
          ]
      }
      

      Example 2 : Paris -> Milano (One Way Flight)

      {
          "travel": {
              "number_of_travellers": 3,
              "departure_date": "2019-06-14",
              "departure_city": "Paris",
              "departure_airport": "CDG",
              "departure_country": "FR",
              "return_date": "none",
              "destination_city": "Milano",
              "destination_airport": "MXP",
              "destination_country": "IT",
              "buy_date": "2019-05-10",
              "insurance": true
          },
      }
      
    • Accomodation merchants : merchant_data value is any merchant-specific data in JSON format.

      {
          "stay": {
              "reference": "Edenarc",
              "duration_days": 7,
              "name": "2 single beds - standard category",
              "amount_cents": 99700,
              "merchant_data": {
                  "category": "apparthotel"
              },
              "insurance": true,
              "arrival_date": "2019-06-14",
              "departure_date": "2019-06-14",
              "country": "FR",
              "location": "Les Arcs",
              "number_of_adults": 2,
              "number_of_children": 2
          }
      }
      
    • Retail merchants : The possible values for the field delivery_mode are the following: home, relay.

      The possible values for the field delivery_speed are the following:

      • 1 : Express (less than 24 hours)
      • 2 : Standard
      • 3 : Click and Collect
      • 4 : Instant

      The possible values for the field type are the following: physical, virtual.

      The possible values for the field category are the following:

      • 1 : Food & Gastronomy
      • 2 : Auto & Moto
      • 3 : Culture & Entertainment
      • 4 : Home & Garden
      • 5 : Home appliance
      • 6 : Auctions and Group Purchases
      • 7 : Flowers & Gifts
      • 8 : Computers & Software
      • 9 : Health beauty
      • 10 : Particular services
      • 11 : Professional services
      • 12 : Sport
      • 13 : Clothing & Accessories
      • 14 : Travel & Tourism
      • 15 : HiFi, Photo & Videos
      • 16 : Telephony & Communication
      • 17 : Jewelry & Precious Metals
      • 18 : Baby items and accessories
      • 19 : Sound & Light

      merchant_data value is any merchant-specific data in JSON format.

      {
          "delivery_mode": "home",
          "delivery_speed": 2,
          "products": [{
              "reference": "xxx",
              "type": "physical",
              "quantity": 1,
              "name": "string",
              "unit_amount_cents": 0,
              "category": 15,
              "merchant_data": {
                  "category_path": "Electronics Store > Widgets",
                  "global_trade_item_number": "1234567",
                  "manufacturer_part_number": "ABCDEF",
                  "brand": "Some brand"
              }
          }]
      }
      

# Signature of the parameters

The settings can be signed through an additional setting called signature which contains a JSON Web Token (JWT).

This token is generated with a secret shared between Pledg and the merchant. The merchant uses this secret on its backend to generate the token, and Pledg uses the same secret to decode it.

The merchant can also specify a validity period when generating the token.

The payload of the token is a JSON containing all the settings normally passed to the solution, except:

  • The parameter signature itself
  • The callbacks (in integration by plugin)
  • The parameter containerElement (if any, in integration by plugin)

Here is an example of code generating the token on the backend of the merchant. In this example, the frontend of the merchant sends a request to the backend of the merchant with a JSON containing all the parameters passed to the solution, so that the backend of the merchant signs them:

app.post('/generate-signature', function (req, res) {
    data = req.body
    var jwt = require('jsonwebtoken');
    var signature = jwt.sign(
        {
            data:data,
        },
        process.env.SECRET,
        { expiresIn: '1d' }
    );
    res.send(JSON.stringify(signature))
});

Many technical resources related to JWT (documentation, validation tools, etc.) are available on https://jwt.io.