Overview

The own form integration provides you with complete control of the checkout experience whilst keeping the PCI requirements at a minimum. Key benefits of the own form integration include:

If you wish to integrate using your own form, 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>

With the sagepay.js you can securely transmit sensitive card data from the customer’s browser to Sage Pay without any details passing through your server.

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"
}

The vendorName field needs to be populated with your unique Sage Pay vendor name.

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 form

ou will also need to include the Sagepay JavaScript library in the page where you will be collecting card details.

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

You will need to collect the following card details:

Be sure not to set a name attribute on these fields, this will ensure they are not submitted to your server.

Here is an example card form:

<form>
    <input data-card-details="cardholder-name">
    <input data-card-details="card-number">
    <input data-card-details="expiry-date">
    <input data-card-details="security-code">
</form>

Step 3: Load the form and create a card identifier

You now need to load the form with the embedded merchantSessionKey and sagepay.js and call the Sagepay.tokeniseCardDetails to tokenise the card details, as per the example payment form.

<!DOCTYPE html>
<html>
<body>
  <form method="post">
    <label>Name:</label><div><input data-card-details="cardholder-name"></div>
    <label>Card:</label><div><input data-card-details="card-number"></div>
    <label>Expiry:</label><div><input data-card-details="expiry-date"></div>
    <label>CVV:</label><div><input data-card-details="security-code"></div>

    <input type="hidden" name="card-identifier">
    <div><input type="submit"></div>
  </form>
  <script src="https://pi-test.sagepay.com/api/v1/js/sagepay.js"></script>
  <script>
    document.querySelector('[type=submit]')
            .addEventListener('click', function(e) {
                e.preventDefault(); // to prevent form submission
                sagepayOwnForm({ merchantSessionKey: 'FC71C349-3AFE-44CF-915D-7E0A46375B41' })
                  .tokeniseCardDetails({
                      cardDetails: {
                         cardholderName: document.querySelector('[data-card-details="cardholder-name"]').value,
                         cardNumber: document.querySelector('[data-card-details="card-number"]').value,
                         expiryDate: document.querySelector('[data-card-details="expiry-date"]').value,
                         securityCode: document.querySelector('[data-card-details="security-code"]').value
                      },
                      onTokenised : function(result) {
                        if (result.success) {
                          document.querySelector('[name="card-identifier"]').value = result.cardIdentifier;
                          document.querySelector('form').submit();
                        } else {
                          alert(JSON.stringify(result));
                        }
                      }
                  });
            }, false);
  </script>
</body>

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

Next