NAV Navbar
Logo
PHP Python cURL

Overview

Make sure to read the Integrated Payments Overview to discover how it works.

Versions

<!-- Load the `Integrated Payments` library in your page. -->
<script type="text/javascript" 
        src="https://cdn.payplug.com/js/integrated-payment/v1@1/index.js">
</script>

Follow the example to load the library on your page.
We provide fixed versions at the following URLs : https://cdn.payplug.com/js/integrated-payment/v<major-version>@<version-selector>/index.js.
For example, the <version-selector> can by major 1 or feature 1.4 or full 1.4.5.

Test mode

Integrated Payments can be created in LIVE or TEST modes. To specify which mode should be used, simply set the test_mode parameter in the constructor. If no value is set, the default created mode would be LIVE

Mode test_mode value
Live false
Test true

IntegratedPayment

The IntegratedPayment class is made to create and handle a payment form in your page.

Constructor

// Create an instance of Integrated Payments
const intPayment = new Payplug.IntegratedPayment(
    false  // The test_mode value in order to specify if the instance of Integrated Payment should be created in test mode. Default being false
);

IntegratedPayment(test_mode: boolean)

Construct an IntegratedPayment object.

Create elements

// Add each payments fields
intPayment.cardHolder(document.querySelector('#cardholder-input-container'));
intPayment.cardNumber(document.querySelector('#pan-input-container'));
intPayment.cvv(document.querySelector('#cvv-input-container'));
intPayment.expiration(document.querySelector('#exp-input-container'));

// Add each payments fields with exp date in 2 fields
intPayment.cardHolder(document.querySelector('#cardholder-input-container'));
intPayment.cardNumber(document.querySelector('#pan-input-container'));
intPayment.cvv(document.querySelector('#cvv-input-container'));
intPayment.expirationMonth(document.querySelector('#exp-month-input-container'));
intPayment.expirationYear(document.querySelector('#exp-year-input-container'));

Please find below our different prototypes to create elements:

For expiration fields, you can integrate in two ways. First way is by using one field which contains the month and year.
The second is by splitting it in two fields, one for month and one for year.

or

Parameters:

Returns an instance of IntegratedPaymentElement (see IntegratedPaymentElement).

style argument reference

{
   default: {
      color: '#9923DD',
      fontFamily: 'sans-serif',
      textAlign: 'center',
      '::placeholder': {
         color: '#31393C',
      },
      ':focus': {
         color: '#32936F',
      },
      ':hover': {
         font_weight: '900',
      },
      '::selection': {
         color: '#FFBF00',
      },
   },
   invalid: {
      color: 'rgb(245,100,118)',
   },
   placeholder: 'Enter your card number',
}

It is an object whose first-level keys are:

Each one can contain those pseudo-elements or pseudo-classes:

And the only properties allowed are the following ones:

Schemes

const schemes = intPayment.getSupportedSchemes();
/*
   schemes = [
     {
        id: 0,
        name: 'DEFAULT',
        title: 'Auto',
        iconUrl: 'https://secure.payplug.com/.../auto_light.svg',
      },
      ...
   ]
 */

IntegratedPayment.getSupportedSchemes()

Provide a list of supported schemes by Integrated Payments.

Returns an array of object with the following properties.

Key Type Description
id number The scheme ID to provide on pay() method
name string A technical name of scheme
title string The scheme name to display
iconUrl string The scheme logo for display

Check if the form is valid

// Subscribe to validateForm event
MY_FORM.addEventListener('submit', () => {
    intPayment.validateForm();
});

// Listen to the validateForm Event
inPayment.onValidateForm(({isFormValid}) => {
    if(isFormValid) {
       // Form is valid, you can proceed with transaction
    } else {
       // Form is invalid
    }
});

IntegratedPayment.validateForm()

IntegratedPayment.onValidateForm({isFormValid} => {})

We highly recommend that you validate the form before submitting data to our API by using this method.

Validating the form works in two steps, registering a callback and triggering the validation.

To trigger the validation : you call the function IntegratedPayment.validateForm()

To register the callback: you call the function IntegratedPayment.onValidateForm(callback: function(event)). The callback function is called when the form has been validated. The callback function receives a parameter that is an event object.

The event parameter is an object with these properties :
Key | Type | Description
————-|——–|———————
isFormValid | bool | Form is valid or not

Trigger a payment

intPayment.pay('pay_5iHMDxy4ABR4YBVW4UscIn', Payplug.Scheme.AUTO, {save_card: false});

IntegratedPayment.pay(payment_id: string, scheme: Scheme, options: {save_card: boolean})

Trigger a payment attempt.

An exception will be raised for one of the following reasons:

The full list of errors can be found here

The method returns a boolean indicating whether the payment attempt was triggered or not. An attempt not triggered could be because:

Once the attempt is successfully triggered, the payment attempt occurs asynchronously, and the callback to IntegratedPayment.onCompleted will be fired when it is done.

Manage 3DS

Choose 3DS display mode

intPayment.setDisplayMode3ds(PayPlug.DisplayMode3ds.LIGHTBOX)

IntegratedPayment.setDisplayMode3ds(displayMode3ds: DisplayMode3ds)

Set the display mode to use for 3DS.

Before 3DS

intPayment.onBefore3ds(() => {
    //Do something before 3DS is triggered
});

IntegratedPayment.onBefore3ds(callback: function)

Callback that is called just before the 3DS takes place if the 3DS display mode is REDIRECTED or LIGHTBOX. The callback must be a function with the following signature: function().

Perform 3DS in CUSTOM display mode

intPayment.onPerform3ds((event) => {
    //Display the 3DS url to a new window
    window.open(event.url3ds, '_blank');
});

IntegratedPayment.onPerform3ds(callback: function(event))

Callback that is called when a payment needs 3DS validation from customer.
This callback is called only if you set the DisplayMode3ds PayPlug.DisplayMode3ds.CUSTOM.
The callback must be a function with the following signature: function(event). The event parameter is an object with this attribute list:

Key Type Description
url3ds string The 3DS url for validation from customer

After payment

intPayment.onCompleted((event) => {
    if(event.error) {
        // manage the error
        return;
    }
    //Retrieve payment status from your back-end
});

IntegratedPayment.onCompleted(callback: function(event))

You should retrieve the status of the payment from your back-end once an attempt has been made.

This callback can be called in theses cases:

The callback must be a function with the following signature: function(event). The event parameter is an object with this attribute list:

Key Type Description
token string The payment_id of the completed payment.
error Object or null The error if any.

IntegratedPaymentElement

PayPlug.IntegratedPaymentElement

This class represents an input from the payment form. There is bidirectional communication between the element and your code thanks to the following interface:

Actions

Use the following methods to alter the inputs programmatically:

panElement.focus();

IntegratedPaymentElement.focus()

Set the focus to the selected input

panElement.blur();

IntegratedPaymentElement.blur()

Remove the focus from the selected input

panElement.clear();

IntegratedPaymentElement.clear()

Clear the input

Callbacks

Register callbacks on elements with the following methods:

panElement.onReady(() => {
    //Handling ready event
});

IntegratedPaymentElement.onReady(callback: function)

Triggered when the input is ready to accept user input.

panElement.onChange((event) => {
    if (!event.valid) {
        //Show error message to customer
    }
});

IntegratedPaymentElement.onChange(function(valid: boolean, error: Object | null))

Triggered when the input value has changed.

Key Type Description
valid bool Whether the value of the input has a valid format or not.
error object/null See Errors section below 
panElement.onFocus(() => {
    //Handling focus event
});

IntegratedPaymentElement.onFocus(function)

Triggered when the input gains focus.

panElement.onBlur(() => {
    //Handling blur event
});

IntegratedPaymentElement.onBlur(function)

Triggered when the input loses focus.

panElement.onCardSchemeChange((event) => {
    //Handling scheme change event
});

IntegratedPaymentElement.onCardSchemeChange(callback: function)

Triggered when scheme has change.

Key Type Description
scheme object Current scheme value
oldScheme object Scheme value before it was changed

Style and class

.integrated_payment_error
{
  border: 3px solid red;
}

During validation of each Element input, IntegratedPayment can change the class of your container element.

If the input is invalid your container will get the class integrated_payment_error to notify your user where is the error.

Errors

Integrated Payment Library can send you some kind of errors:

All errors are object like:

{
  name: 'INVALID_EXPIRATION_DATE',
  message: 'Expiration date is not valid'
}
Attribute Contain
name technical name of the error, usable for code
message technical description of this error, more readable for a human. It’s a destiny of you not for your customer.

During initialisation

During the initialization phase, some exceptions can be thrown.

UniqueCardNumberInFormAllowedError

You receive this Error when you create multiple cardNumber elements. If you really need to have multiple payment forms,
you need create an instance of IntegratedPayment for each form.

try {
    integratedpayment.cardNumber(...);  // this call is okay
    integratedpayment.cardNumber(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_CARD_NUMBER_IN_FORM_ALLOWED'
    // error.message = 'Only one card number element can be add in a form'
}

UniqueElementInFormAllowedError

try {
    integratedpayment.expiration(...);  // this call is okay
    integratedpayment.expiration(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_EXP_IN_FORM_ALLOWED'
    // error.message = 'Only one element of the type Exp can be added in a form'
}

try {
    integratedpayment.expirationMonth(...);  // this call is okay
    integratedpayment.expirationMonth(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_EXP_MONTH_IN_FORM_ALLOWED'
    // error.message = 'Only one element of the type Exp_month can be added in a form'
}

try {
    integratedpayment.expirationYear(...);  // this call is okay
    integratedpayment.expirationYear(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_EXP_YEAR_IN_FORM_ALLOWED'
    // error.message = 'Only one element of the type Exp_year can be added in a form'
}

try {
    integratedpayment.cvv(...);  // this call is okay
    integratedpayment.cvv(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_CVV_IN_FORM_ALLOWED'
    // error.message = 'Only one element of the type Cvv can be added in a form'
}

try {
    integratedpayment.cardHolder(...);  // this call is okay
    integratedpayment.cardHolder(...);  // this call throws an exception
} catch(error) {
    // error.name = 'ERROR_UNIQUE_CARDHOLDER_IN_FORM_ALLOWED'
    // error.message = 'Only one element of the type Cardholder can be added in a form'
}

You receive this Error when you create multiple of the same elements. If you really need to have multiple payment forms, you need create an instance of IntegratedPayment for each form.

UnsupportedBrowserError

try {
    integratedpayment = new Payplug.IntegratedPayment();
} catch(error) {
    // error.name = 'UNSUPPORTED_BROWSER'
    // error.message = 'Your browser is not supported by Integrated Payment'
}

You receive this Error when a customer try to use Integrated Payment on an unsupported browser (e.g. IE).

During typing

This kind of error is sent from the onChange callback.

INVALID_CARD_NUMBER

const card = integratedpayment.cardNumber(...);
card.onChange(event) {
    if(event.error) {
        // event.error.name = 'INVALID_CARD_NUMBER'
        // event.error.message = 'Card number is not valid'
    }

You receive this error if the user enters a card number in a bad format. The main check is the Luhn’s check.

INVALID_EXPIRATION_DATE

const exp = integratedpayment.exp(...);
exp.onChange(event) {
    if(event.error) {
        // event.error.name = 'INVALID_EXPIRATION_DATE'
        // event.error.message = 'Expiration date is not valid'
    }

You receive this error if the user enters a date in the past or an incorrect date format.

The date format is valid if :

INVALID_CVV

const exp = integratedpayment.cvv(...);
cvv.onChange(event) {
    if(event.error) {
        // event.error.name = 'INVALID_CVV'
        // event.error.message = 'Cvv is not valid'
    }

You receive this error if the user enters a cvv in a bad format. The CVV must be 3 digits.

INVALID_CARDHOLDER

const ch = integratedpayment.cardHolder(...);
cvv.onChange(event) {
    if(event.error) {
        // event.error.name = 'INVALID_CARDHOLDER'
        // event.error.message = 'Cardholder is not validd'
    }

You receive this error if the cardholder name was invalid. The cardholder must be composed of 5 to 45 characters.

During payment

You receive these errors in the onCompleted callback. In fact, these errors can be sent after a call to the pay() method.

INVALID_TOKEN

try {
    integratedpayment.pay('a_bad_token', ...);
} catch(error) {
    // event.error.name = 'INVALID_TOKEN'
    // event.error.message = 'Payment token is not defined or his format is invalid'
}

You receive this message when you send to pay method a bad token format. You need to create a payment by calling PayPlug API.

FORBIDDEN

integratedpayment.onComplete(event) {
    if(event.error) {
        // event.error.name = 'FORBIDDEN'
        // event.error.message = 'Your PayPlug account can't use this feature'
    }
}

You receive this error if Payplug API does not authorize your account to use IntegratedPayment.

NOT_FOUND

integratedpayment.onComplete(event) {
    if(event.error) {
        // event.error.name = 'NOT_FOUND'
        // event.error.message = 'Payment not found'
    }
}

You receive this message when PayPlug API does not retrieve your payment_id.

SERVER_ERROR

integratedpayment.onComplete(event) {
    if(event.error) {
        // event.error.name = 'SERVER_ERROR'
        // event.error.message = 'Error in server'
    }
}

You receive this message when the PayPlug API encounters a problem. You can retry the payment later.

ELEMENT_NOT_FOUND

const integratedpayment = new Payplug.IntegratedPayment();
integratedpayment.cardNumber(...);
integratedpayment.cardHolder(...);
integratedpayment.expirationDate(...);
integratedpayment.onComplete(event) {
    if(event.error) {
        // event.error.name = 'ELEMENT_NOT_FOUND'
        // event.error.message = 'Element Cvv not found'
    }
}

You receive this message when you forgot to create an essential element of your payment form.

INVALID_FORM

integratedpayment.onComplete(event) {
    if(event.error) {
        // event.error.name = 'INVALID_FORM'
        // event.error.message = 'One or more fields are empty or invalid'
    }
}

You receive this message when your customer does not fill some elements or some values are invalid.

FIELD_EMPTY

cvv.onChange(event) {
    if(event.error) {
        // event.error.name = 'FIELD_EMPTY'
        // event.error.message = 'Field Cvv is empty'
    }
}

You receive this message when your customer does not fill this element.

PHP Python cURL