Overview

Our drop-in checkout integration provides you with a flexible form that enables seamless integration with your payment pages. Key benefits of our drop-in checkout integration include:

If you wish to integrate using the drop-in checkout, you will need to include our JavaScript library (sagepay.js) when your payment page is loaded.

<script src="https://pi-test.sagepay.com/api/v1/js/sagepay.js"></script>

You will need to secure your site with TLS (1.2 or latest version) and ensure all communications are over HTTPS. You will also need to ensure that you have your Integration Key and Integration Password in order to authenticate your requests.

If you don’t have your credentials please see how to get your PI credentials

To begin your integration, just follow the simple guide below:

Step 1: Create a merchant session key (MSK)

The first thing you need to do is to generate a Merchant Session Key using your Integration Key and Integration Password in order to authenticate your requests.

You need to create a merchantSessionKey every time you load the payment page, or if an existing Merchant Session Key has expired or became invalid.

The Merchant Session Key expires after 400 seconds and can only be used to create one successful Card Identifier (tokenised card details). It will also expire and be removed after 3 failed attempts to create a Card Identifier.

To do this you will need to send a HTTP POST request to our /merchant-session-keys endpoint whilst using your integration key and password to authenticate your request.

curl https://pi-test.sagepay.com/api/v1/merchant-session-keys \
-H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRVM4Q0RSRkxodUo4RzU0TzZyRHBVWHZFNmhZRHJyaWE6bzJpSFNyRnliWU1acG1XT1FNdWhzWFA1MlY0ZkJ0cHVTRHNocktEU1dzQlkxT2lONmh3ZDlLYjEyejRqNVVzNXU="  \
-H "Content-type: application/json" \
-X POST \
-d '{
  "vendorName": "sandbox"
}'

A successful request will receive a response similar to the one below:

{
  "merchantSessionKey" : "M1E996F5-A9BC-41FE-B088-E5B73DB94277",
  "expiry" : "2015-08-11T11:45:16.285+01:00"
}

A valid merchantSessionKey is required to initialise the drop-in checkout.

NOTE: To handle the scenario where a merchant session key becomes invalid, you can create an endpoint on your server that generates a new merchant session key for the current transaction. When you get a HTTP 401 (Unauthorised), you can make an AJAX request to that endpoint and replace the merchant session key in the page with the one obtained. This also handles the scenario where the merchant session key has expired (after 400s).

For HTTP Basic authentication, you will need to combine into a string the “integrationKey:integrationPassword”. The resulting string will have to be encoded using Base64 encoding. The encoded string will have to be included in the Authorization header.

Step 2: Include sagepay.js in your payment page

You will also need to include the Sagepay JavaScript library in the page where you want the drop-in checkout iFrame to be displayed.

<script src="https://pi-test.sagepay.com/api/v1/js/sagepay.js"></script>

Step 3: Create a container for the iFrame

You now need to specify an HTML element that will serve as the container for the iFrame (this will typically be a div) as per the example below:

<div id="sp-container"></div>

Step 4: Call sagepayCheckout

To initialise the iFrame you have to make a call to sagepayCheckout with the merchant session key and any additional options.

If the container is given the id sp-container, then the only parameter that needs to be provided to the function is the obtained merchant session key. Here is an example of a simple call where this setup uses the form that contains the iFrame container you specified earlier:

<script>
  sagepayCheckout({ merchantSessionKey: 'F42164DA-4A10-4060-AD04-F6101821EFC3' }).form();
</script>

If you would rather use a different form, then the formSelector option needs to be provided together with the form’s CSS selector.

<script>
  sagepayCheckout({
    merchantSessionKey : 'M1E996F5-A9BC-41FE-B088-E5B73DB94277',
    containerSelector:  '#payment-details'
  }).form({
    formSelector: '#checkout-form'
  });
</script>

If you want to specify the container, then the containerSelector option needs to be specified with the appropriate CSS selector.

Once the customer initiates the form submission, the payment details are validated, tokenised and passed as a hidden field called cardIdentifier which is then posted with the rest of the form contents.

A successful call will create a cardIdentifier and you just need to submit a payment from your server to complete the transaction.

Here is an example of a payment form using drop-in checkout:

<html>
  <head>
    <script src="https://pi-test.sagepay.com/api/v1/js/sagepay-dropin.js"></script>
    <style>
      body * {
          font-family: sans-serif;
      }
      h1 {

      }
      input {
          font-size:12pt;
      }
      #main {
          width: 550px;
          margin: 0 auto;
      }
      #submit-container {
          padding-top:10px;
          float:right;
      }
      input[type=submit] {
          border:none;
          background:indigo;
          padding:10px;
          color:white;
          border-radius:5px;
      }
    </style>
  </head>
  <body>
    <div id="main">
      <h1>My Test Shop</h1>
      <form>
        <h2>Payment Details</h2>
        <div id="sp-container"></div>
        <div id="submit-container">
         <input type="submit"/>
        </div>
      </form>
    </div>
    <script>
      sagepayCheckout({ merchantSessionKey: 'F42164DA-4A10-4060-AD04-F6101821EFC3' }).form();
    </script>
  </body>

Next