Integrate Our Drop-In Checkout

On this page:

Overview

Our Drop-In Checkout integration gives you a flexible form that is integrated seamlessly with your payment pages.

Benefits

Key benefits include:

  • Using the SAQ-A self-assessment questionnaire to help you become PCI-DSS compliant
  • You can choose basic and advanced options that ensure maximum compatibility with your payment pages
  • Mobile-first design optimises multichannel experiences
  • You retain control of the checkout customer journey

Integration

You can integrate with our Drop-In Checkout in only 3 steps. You must first ensure:

  • Your site is secured using TLS (1.2, or the latest version)
  • All communications are over HTTPS
  • You have your Integration Key and Integration Password in order to authenticate your requests. (Read Authentication and Credentials)
Important: You must keep your Integration Key and Integration Password secret!

  • You add the following link to our JavaScript library (sagepay.js) on your payment page:

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

Note: The sagepay.js ensures sensitive card data is transmitted directly from the customer's browser to Opayo without any details passing through your server.

Step 1. Create a merchant session key (MSK)

Important: A valid merchantSessionKey is required to initialise the Drop-In checkout.

Generate a Merchant Session Key (merchantSessionKey) using your Integration Key and Integration Password to authenticate your requests.

The Merchant Session Key is used to create a unique Card Identifier (tokenised card details). It expires:

  • After 400 seconds
  • After 3 failed attempts to create a Card Identifier

A new Merchant Session Key must be created each time you load the payment page, or when an existing Merchant Session Key has expired. Send an HTTP POST request to our merchant-session-keys endpoint using your Integration Key and password to authenticate the request.

Example request

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

For HTTP Basic Authentication, you must format the string as, 'integrationKey:integrationPassword' and encode it using Base64 encoding. The encoded string must be included in the Authorization header.

Example Response

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

Notes: 

  • When a Merchant Session Key is invalid, or when the Merchant Session Key has expired (after 400s), 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) response, you can make an AJAX request to the same endpoint and replace the Merchant Session Key in the page with the new one.

Step 2. Include sagepay.js in your payment page

You must include the link to the Sagepay JavaScript library in the code of the page where you want the Drop-In Checkout iFrame to display as follows:

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

Step 3. Create a container for the iFrame

Create the HTML element that will contain the iFrame. A div element is used in the following example:

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

Step 4. Call sagepayCheckout

Initialise the iFrame with a call to sagepayCheckout including the merchant session key and any additional options:

  • When the container has the id of ‘sp-container’, then only Merchant Session Key is required. For example:
    <script>sagepayCheckout({ merchantSessionKey: 'F42164DA-4A10-4060-AD04-F6101821EFC3' }).form(); </script>
  • To use a different form, include the formSelector option together with the form's CSS selector. For example:
    <script>
sagepayCheckout({ merchantSessionKey : 'M1E996F5-A9BC-41FE-B088-E5B73DB94277',
containerSelector: '#payment-details' }).form({ formSelector: '#checkout-form' });
</script>
  • To specify a custom container, include the containerSelector option together with the custom CSS selector.

When your customer submits the form, their payment details are:

  • Validated
  • Tokenised
  • Passed in the hidden cardIdentifier field to POST with the form data
Important: You must Submit Payments from Your Server to complete the transaction.

Example payment form using the Drop-In Checkout

<!DOCTYPE html>
<html lang="en">
<head>
<title>Payment Form</title>
<script src="https://pi-test.opayo.co.uk/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; }
    button[type=submit] { border:none; background:indigo; padding:10px; color:white; border-radius:5px; }
 </style>
 </head>
<body>
<main>
 <h1>My Test Shop</h1>
<form>
  <h2>Payment Details</h2>
  <div id="sp-container"></div>
  <div id="submit-container">
   <button type="submit">Make Payment</button>
  </div>
</form>
</main>
 <script>sagepayCheckout({ merchantSessionKey: 'F42164DA-4A10-4060-AD04-F6101821EFC3' }).form(); </script>
</body>
</html>

Next Steps

 

❮ Back to Overview Next: Integrate Your Own Form ❯