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 per Payment type

Name	Payment type	Type	Details
`amountCents`	all	`integer`	Purchase amount in cents
`merchantUid` or `companyUid`	all	`string`	Your merchant (1 single payment solution) or company id (1 to N payment solution(s)).
`email`	all	`string`	Email of the client
`firstName`	all	`string`	First name of the client. Some controls on length, restricted words, etc... may apply
`lastName`	all	`string`	Last name of the client. Some controls on length, restricted words, etc... may apply
`reference`	all	`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`	all	`string`	Title of the purchase

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": "2026-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 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
`birthZipcode`	`string`	Customer birth zip code, required only if `birthCountry` is FR	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 is supported)	Not Used
`language`	`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:[email protected]) 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
`signature`	`string`	Signature of all the parameters except, of course, the signature itself (see Signature).	Not Used
`showCloseButton`	`boolean`	Indicates whether the button on the upper right corner should be displayed (true by default).	Not Used
`civility`	`string`	Customer civility (`Mr` or `Ms`)	Used
`birthLastName`	`string`	Customer birth last name	Not Used
`nationality`	`string`	Customer nationality	Not 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 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
`transactionExpirationDatetime`	`string`	Specifies the transaction expiration date and time in UTC, using the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Use only if the transaction is time-limited. Example: 2025-01-01T14:14:15Z	Not used

Signed only settings

Name	Type	Details	Scoring
`paymentMethodId`	`string`	A psp identifier for the client payment method. Add this parameter to the signature only without sending it in the body	Not Used

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 (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 (i.e. FR for France).

For marketplaces, please fill in the reseller_data section(s) where appropriate.

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.

json

{
    "session": {
        "duration_seconds": 4612,
        "channel":  "desktop"
    }
}

Scoring data about the account:

json

{
    "account": {
        "creation_date": "2019-06-13",
        "number_of_purchases": 14,
        "loyalty_card_number": "XYZ64"
    }
}

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. These fields also support IATA railway station codes.

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

json

{
    "travel": {
        "number_of_travellers": 3,
        "departure_date": "2025-06-14",
        "departure_city": "Paris",
        "departure_airport": "CDG",
        "departure_country": "FR",
        "return_date": "2025-06-30",
        "destination_city": "Milano",
        "destination_airport": "MXP",
        "destination_country": "IT",
        "buy_date": "2025-05-10",
        "insurance": true,
        "reseller_data": {
           .../...
           <please refer to `reseller_data` in _Service & Ticketing merchants_ section below>
           .../...
           }
    },
    "travellers": [{
            "id": "xxx1",
            "buyer": true,
            "birth_date": "1980-01-21",
            "document": {
                "type": "passport",
                "validity_date": "2026-02-18",
                "country": "FR"
            }
        },
        {
            "id": "xxx2",
            "buyer": false,
            "birth_date": "1982-03-17",
            "document": {
                "type": "passport",
                "validity_date": "2027-10-18",
                "country": "ES"
            }
        },
        {
            "id": "xxx3",
            "buyer": false,
            "birth_date": "2019-03-15"
        }
    ]
}

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

json

{
    "travel": {
        "number_of_travellers": 3,
        "departure_date": "2025-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": "2025-05-10",
        "insurance": true,
        "reseller_data": {
           .../...
           <please refer to `reseller_data` in _Service & Ticketing merchants_ section below>
           .../...
           }
    },
}

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

json

{
    "stay": {
        "reference": "Edenarc",
        "duration_days": 7,
        "name": "2 single beds - standard category",
        "amount_cents": 99700,
        "merchant_data": {
            "category": "apparthotel"
        },
        "insurance": true,
        "arrival_date": "2025-06-14",
        "departure_date": "2025-06-14",
        "country": "FR",
        "location": "Les Arcs",
        "number_of_adults": 2,
        "number_of_children": 2,
        "reseller_data": {
           .../...
           <please refer to `reseller_data` in _Service & Ticketing merchants_ section below>
           .../...
           }
    }
}

Retail merchants : The possible values for the field delivery_mode are the following: home, relay, clickAndCollect.
The field delivery_mode_reference is linked to delivery_mode. Please follow these recommendations:
- if delivery_mode = home : express, standard, appointment, etc...
- if delivery_mode = relay : Mondial relay, La Poste, etc...
- if delivery_mode = clickAndCollect : 2h, 3h, etc...
The type of the delivery_delay field is integer and represents the delay in days between the order and the estimated time of receipt by the customer.
The possible values for the field type are the following: physical, virtual.
Field discount: boolean value (true or false) to describe if the purchase is part of a promotion offer, or not.
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
json
```
{
    "products": [{
        "reference": "5025155081754",
        "type": "physical",
        "quantity": 1,
        "name": "Vacuum cleaner Dyson V15 Detect Absolute",
        "unit_amount_cents": 59900,
        "category": 5,
        "sub_categories": ["electronic home & comfort", "vacuum cleaner", "broom vacuum cleaner", "cordless stick vacuum cleaner", "..."],
        "brand": "Dyson",
        "size": "126cm",
        "color": "purple",
        "discount": true,
        "stock": false,
        "delivery_mode": "home",
        "delivery_mode_reference" : "standard",
        "delivery_delay": 84,
        "reseller_data": {
           .../...
           <please refer to `reseller_data` in _Service & Ticketing merchants_ section below>
           .../...
           },
    }]
}
```

Service & Ticketing merchants:

json

{
    "event": [
       {
       "description": "String",
       "category": "String", (e.g: concert, match, theater)
       "sub_category": "String", (e.g: rock, tennis ...)
       "ticket_nb": 4, (number of participants, type integer) 
       "ticket_class": "String", (e.g: VIP / 1 / 2 ...)
       "reference": "String",
       "beginning_date": "2022-06-18",
       "duration_days": 3, (event duration, type integer)
       "reseller_data": {
          "name": "String",
          "national_id": "123456789",
          "national_id_type": "SIREN", (Must be part of the supported types of national ids, e.g: SIREN for France)
          "country_code": "FR", (The country code of the company: UK, FR, BE, CH, .../...)
          "email": "[email protected]",
          "phone": "+33612345678",
          "address": "3 rue Saint-Lazare 75009 Paris"
          }
       }
       ]
}

Signature of the parameters

The settings must be securely transmitted as a signature which contains a JSON Web Token (JWT).

This token is generated with a secret key shared between Pledg and the merchant. The merchant uses this secret key on its backend to generate the token, and Pledg uses the same secret key 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)

The example code below illustrates how to generate the JWT on the backend of the merchant. More precisely, the JWT is based on the data sent by the frontend, computed on the backend and returned to the frontend.

javascript

const jwt = require('jsonwebtoken');

function generateSignature(data) {
    // The secret key to sign the JWT (It is important to store it in private area)
    const secret = process.env.SECRET;

    // Generate the signature
    const signature = jwt.sign(
        { data: data },       // signed data
        secret,              // Secret Key
        { expiresIn: '1d' } // Options : the signature expires in 1 day
    );

    return signature;
}

// use case
const settings = {merchantUid: 'mer_efjhik1234567', amountCents: 10000, email: '[email protected]', title: 'My Order', reference: 'abcd', phoneNumber: '0664667788'};
const signature = generateSignature(settings);
console.log('generated signature:', signature);

In this particular example:

It is written in JavaScript, but it could be any other backend language (Python, PHP, Java, etc.)

The library jsonwebtoken used here to generate the signature must be installed on the backend. It can be found there with the instructions to install it.
data is the request sent by the frontend, which contains the payload with all the settings of the purchase (merchantUid, amounCents, email, title, etc.)
signature is the response sent back to the frontend, which contains the JWT.
The frontend is then supposed to call the URL of the backend related to the code above, retrieve the JWT from the signature and set it in the field signature.

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

Settings ​

Required settings per Payment type ​

Contractual settings ​

Optional settings ​

Signed only settings ​

Metadata ​

Scoring data about the session: ​

Scoring data about the account: ​

Vertical-specific scoring data: ​

Signature of the parameters ​

Settings

Required settings per Payment type

Contractual settings

Optional settings

Signed only settings

Metadata

Scoring data about the session:

Scoring data about the account:

Vertical-specific scoring data:

Signature of the parameters