Logo blk

Integrate the payment form


You can chose among 3 ways to integrate PayPlug on your website:

  Hosted page Lightbox payplug.js
Preview Hosted page Lightbox payplug.js
Description The customer is redirected to a payment page hosted by PayPlug. The customer stays on your website and the payment will be performed in an embedded payment form hosted by PayPlug. The customer stays on your website and will use your custom payment form.
Customization Limited Extended Full
Securization Fully secured by PayPlug Fully secured by PayPlug You need to secure the payment
Integration None Iframe HTML
Hosting  PayPlug servers PayPlug servers (Iframe) Your server
Difficulty Easy Medium Advanced
PayPlug offer All All
Documentation   Read the doc Read the doc
  Hosted page Hosted page Hosted page


If you do not want to redirect your customers to a payment page hosted by PayPlug, the Lightbox is a quick and simple solution to add an embedded and secure payment form into your website.


This is the easiest way to integrate a PayPlug payment form, as you do not need to handle the security aspect of your customers’ card data.

If you are looking for a full customised payment form, you can create your own payment form with payplug.js.

Create a payment page

$payment = \Payplug\Payment::create(array(
    'amount'         => 3300,
    'currency'       => 'EUR',
    'save_card'      => false,
    'billing'          => array(
        'title'        => 'mr',
        'first_name'   => 'John',
        'last_name'    => 'Watson',
        'email'        => 'john.watson@example.net',
        'address1'     => '221B Baker Street',
        'postcode'     => 'NW16XE',
        'city'         => 'London',
        'country'      => 'GB',
        'language'     => 'en'
    'shipping'          => array(
        'title'         => 'mr',
        'first_name'    => 'John',
        'last_name'     => 'Watson',
        'email'         => 'john.watson@example.net',
        'address1'      => '221B Baker Street',
        'postcode'      => 'NW16XE',
        'city'          => 'London',
        'country'       => 'GB',
        'language'      => 'en',
        'delivery_type' => 'BILLING'
    'hosted_payment' => array(
        'return_url' => 'https://example.net/success?id=42',
        'cancel_url' => 'https://example.net/cancel?id=42'
    'notification_url' => 'https://example.net/notifications?id=42',
    'metadata'        => array(
        'customer_id' => 42

The Lighbox is based on the PayPlug API. To integrate the payment form, first you have to create a simple payment request based on the create payment method.

Include form.js

<script type="text/javascript" src="https://api.payplug.com/js/1/form.latest.js"></script>

To integrate the Lightbox you need the script tag located on the right side. Add this script tag in your code that will serve the payment form.

Call the Lightbox

document.addEventListener('DOMContentLoaded', function() {
  [].forEach.call(document.querySelectorAll("#signupForm"), function(el) {
    el.addEventListener('submit', function(event) {
      var payplug_url = '<?php echo htmlentities($payment->hosted_payment->payment_url); ?>';

In order to display the PayPlug lightbox into your page once your customer clicks on the pay button, add into your code the javascript script from the right side.


If you do not want to redirect your customers to PayPlug’s hosted payment page, you can use payplug.js to securely display the payment form inside your website.


payplug.js encrypts credit card details in the browser and enables you to fully control the user experience without receiving sensitive card data on your server.

The library also provides powerful validators to check the credit card numer format, expiration date, type and CVV number.


  1. Include set-up elements (Js and publishable key)
  2. Create a payment token using payplug.js
  3. Post the token to your server
  4. Create a payment with the API

If you don’t have the time to read the full documentation and if you are really in a hurry to get started, you can go straight to our full example.


If you want to host your own payment page on your website, you must address the following security basics.


Always ensure that all the traffic between your server and your customer browser is encrypted.

We do not support the SSL protocol because it is insecure, and recommend you deactivate SSLv3 from your server. Use TLS v1.1 or v1.2 instead. Finally, we recommand you use HTTPS to serve your web pages.

If you want to test the security of your website, you can use the following tools:

  1. Qualys SSL Server Test, a minimum rate of B is highly recommanded.
  2. Symantec CryptoReport.
  3. SSL Decoder.


To host your own payment page, your website must comply with PCI DSS. You must complete the PCI DSS Self-Assessment Questionnaire (SAQ) to self evaluate your service to PCI compliance. You may need to share these details with PayPlug.

Useful Resources

Here is a small list of very useful articles about server security:

  1. Mozilla Wiki - Security/Server Side TLS.
  2. Mozilla SSL Configuration Generator.
  3. OWASP - Top 10 2013-Top 10.
  4. SSL Certificate Installation Instructions & Tutorials.
  5. PCI SSC Data Security Standards Overview.

3-D Secure

3-D Secure is natively embedded in the payment page when using payplug.js. You do not have to implement any 3-D Secure handing in your integration.

When 3-D Secure is needed, payplug.js displays an overlay pop-up window embedding the 3-D Secure page within an iFrame. 3-D Secure parameter is set in the 3-D Secure configuration screen of the PayPlug Portal and it is not possible to force 3-D Secure for an individual payment within the API.

Include set-up elements

Including payplug.js

<script type="text/javascript" src="https://api.payplug.com/js/1/payplug.latest.js"></script>

To use payplug.js add the opposite script tag in the page that will serve the payment form.

Setting your publishable key


Before using payplug.js you must set your publishable key (available in your account) with setPublishableKey to communicate with PayPlug.

Handling errors

payplug.js indicates errors from the payment form (client side) and shows errors from the API (server side) when there is an issue after submitting the form.

This enables you to handle all error messages within the same script.

Client side error messages

Error example:

  "message":"Problem with publishable key. For more information see PayPlug Documentation (https://www.payplug.com/docs/api)",

payplug.js returns error messages, enabling you to display them directly in the browser.

Error messages format:

Key Description
message string A short human-readable description of the cause of the error.
name string Error message name.

Error messages:

Name Message
publishable_key_not_found The publishable key was not found, you need to use "Payplug.setPublishableKey()".
incorrect_publishable_key The publishable key was incorrect.
payplug_form_not_found Your form need to have an attribute: "data-payplug=’form’" in the field <form>.
card_number_not_found You need to have an input field with attribute: "data-payplug=’card_number’" in your form.
cvv_not_found You need to have an input field with attribute: "data-payplug=’card_cvv’" in your form.
expiry_date_not_found You need to have an input field with attribute: "data-payplug=’card_month_year’" in your form.
card_number_invalid The card number seems to be incorrect.
expiry_date_invalid The date seems to be incorrect, the format is (MM/YYYY).
cvv_invalid  The CVV was invalid.
encrypt_errors A problem occurred during encryption of card data.
payplug_api_error Error message sent by the API. All API error messages are described in the API Reference.

Client-side validation

Card number validation:

Payplug.card.validateCardNumber('4242 4242 4242 4242') // true
Payplug.card.validateCardNumber('4242-4242-4242-4242') // true
Payplug.card.validateCardNumber('4242424242424242')    // true
Payplug.card.validateCardNumber('5184-9200-0000-0097') // false
Payplug.card.validateCardNumber('this-is-a-card')      // false
Payplug.card.validateCardNumber('123456789')           // false

 Card expiration validation:

Payplug.card.validateExpiry('08/2020') // true
Payplug.card.validateExpiry('08/20')   // true
Payplug.card.validateExpiry('8/20')    // true
Payplug.card.validateExpiry('8/2020')  // true
Payplug.card.validateExpiry('08/10')   // false
Payplug.card.validateExpiry('08/2010') // false
Payplug.card.validateExpiry('08 2020') // false
Payplug.card.validateExpiry('08-2020') // false
Payplug.card.validateExpiry('2020/08') // false

CVV validation:

Payplug.card.validateCVV('123')  // true
Payplug.card.validateCVV('1234') // false
Payplug.card.validateCVV('12')   // false
Payplug.card.validateCVV('')     // false

Card type validation:

Payplug.card.cardType('4242424242424242') // visa
Payplug.card.cardType('5500005555555559') // mastercard
Payplug.card.cardType('5555222211111111') // null

payplug.js provides a client-side validation, which allows to check the validity of the payment card, the CVV, the card type and the card expiration.

Validation Description
Payplug.card.validateCardNumber Returns true or false Checks the number format and the Luhn algorithm. Compliance space or any other punctuation characters will be ignored.
Payplug.card.validateExpiry Returns true or false Checks if the expiration date is a date in the future.
Payplug.card.validateCVV Returns true or false Check if the CVV could be a valid verification code.
Payplug.card.cardType Returns visa, mastercard or null Checks the payment card number and return the type of the card.

Create a payment token

To create a payment page on your own website with payplug.js :

  1. create a simple payment form,
  2. paste a few lines of javascript in your page header.

Because your payment form is going to collect very sensitive data, payplug.js prevents them from being routed through your server by converting all sensitive data into an encrypted token. You can then use this token to create a payment with the PayPlug API.


var form = document.querySelectorAll("#signupForm")[0];
Payplug.card.createToken(form, payplugResponseHandler,
  {'amount': 1000,
    'currency': 'EUR',
    'card_number': '4242 4242 4242 4242',
    'card_cvv': 400,
    'card_month': 12,
    'card_year': 2019

Simple example while using data-payplug attribute in your form:

var form = document.querySelectorAll("#signupForm")[0];
Payplug.card.createToken(form, payplugResponseHandler,
  {'amount': 1000,
    'currency': 'EUR'

Form example using the data-payplug attributes:

<form action="" method="post" id="signupForm" class="form" novalidate data-payplug="form">
  <div class="input-error-wrapper" id="error-api">
    <p class="input-error" id="error-api-bad"></p>
    <input type="text" class="form-control" placeholder="First Name" name="firstname" value="" >
    <input type="text" class="form-control" placeholder="Last Name" name="lastname" value="" >
    <input type="text" placeholder="Email" name="email" value="" >
    <input type="text" placeholder="Card number" value="" data-payplug="card_number" >
  <div class="input-error-wrapper" id="error-card">
    <p class="input-error" id="error-card-bad">Invalid payment card number.</p>
    <input type="text" placeholder="CVV" autocomplete="off" data-payplug="card_cvv">
  <div class="input-error-wrapper" id="error-cvv">
    <p class="input-error" id="error-cvv-bad">Invalid CVV code.</p>
    <input type="text" placeholder="Expiration (MM/YYYY)" data-payplug="card_month_year">
  <div class="input-error-wrapper" id="error-expiry">
    <p class="input-error" id="error-expiry-bad">Invalid credit card expiration date.</p>
    <button type="submit" data-payplug='submit'>Submit payment</button>

Use the createToken function to create a single-use payment token with the following parameters:

Parameters Description
amount positive integer required Amount of the payment in cents.
currency positive integer required Currency code (three-letter ISO 4217) in which the payment was made.
card_number string optional Credit card number.
card_cvv integer optional Credit card CVV.
card_month integer optional Credit card expiration month.
card_year integer optional Credit card expiration year.

As an alternative, you can also assign the required parameters to the data-payplug attribute into your form input fields instead of passing the attributes directly in the createToken function.

If you do not already have your customer e-mail address, do not forget to add an e-mail field in your form, as you will have to provide one to process a payment with the PayPlug API.

To be sure the data are not routed through your server when submitting the form, do not add name attributes in any input fields.

Post the token to your server

var payplugResponseHandler = function(code, response, details) {
  console.log(code + ' : ' + response + ' : ' + details);
  if (code == 'card_number_invalid') {
    document.querySelectorAll("#error-card-bad")[0].style.display = 'block';
  if (code == 'cvv_invalid') {
    document.querySelectorAll("#error-cvv-bad")[0].style.display = 'block';
  if (code == 'expiry_date_invalid') {
    document.querySelectorAll("#error-expiry-bad")[0].style.display = 'block';
  if (code == 'payplug_api_error') {
    document.querySelectorAll("#error-api-bad")[0].innerHTML = response + ', details: ' +  details;
    document.querySelectorAll("#error-api-bad")[0].style.display = 'block';
  return false;

The call payplugResponseHandler handles the response from the API and the payment submission, including any errors that may occur.

If the card information is correct, it will return a single-use payment token to the form in Payplug.card.createToken.

The data from the form is then sent as an HTTP POST to your server, on the URL defined in the action attribute.

Submission to the API

$secretkey = "sk_test_9898098098guGYUG9";

// replace with your own variable
$firstname = htmlspecialchars($_POST['firstname']);
$lastname = htmlspecialchars($_POST['lastname']);
$email = htmlspecialchars($_POST['email']);
$token = $_POST['payplugToken'];


$payment = \Payplug\Payment::create(array(
  'amount'         => 1000,
  'currency'       => 'EUR',
  'payment_method' => $token,
  'billing'  => array(
    'title'        => 'mr',
    'first_name'   => 'John',
    'last_name'    => 'Watson',
    'email'        => 'john.watson@example.net',
    'address1'     => '221B Baker Street',
    'postcode'     => 'NW16XE',
    'city'         => 'London',
    'country'      => 'GB',
    'language'     => 'en'
  'shipping'  => array(
    'title'         => 'mr',
    'first_name'    => 'John',
    'last_name'     => 'Watson',
    'email'         => 'john.watson@example.net',
    'address1'      => '221B Baker Street',
    'postcode'      => 'NW16XE',
    'city'          => 'London',
    'country'       => 'GB',
    'language'      => 'en',
    'delivery_type' => 'BILLING'
  'notification_url' => 'https://example.net/notifications'

Once the form is submitted, the payment card information can now be send to the PayPlug API in the payment_method attribute.

Example in different langage are available in the PayPlug API documentation.