Platform Docs

Using the Clover-hosted iframe

Combining the Clover-hosted iframe (provided by Clover's sdk.js) with an Ecommerce SDK enables you to build fully-featured secure payment experiences on your website.

The following diagram shows the basic flow of required information and the software components that interact to complete a charge request. You add a form to your webpage and insert the Clover-hosted elements to collect and process the user's card information. This information is used to create the card token used by the server to complete the payment. This charge operation must be a server-to-server call. Clover software is shown in green, and your app's software is shown in blue.

Browser support

The iframe is built to work with up-to-date versions of Google Chrome, Mozilla Firefox, and Microsoft Edge. Microsoft Internet Explorer 11 is not supported by default, but you can use polyfills to make the iframe functional in that browser.

<head>
  ...
  <script src="https://cdn.polyfill.io/v3/polyfill.min.js"></script>
  <script src="https://checkout.sandbox.dev.clover.com/sdk.js"></script>
</head>

Adding the Clover SDK to your webpage

Once you add a <script> block to import the Clover SDK, you can use Clover iframe features.

Add a <script> block to your page's <head> block.

<head>
  ...
  <script src="https://checkout.sandbox.dev.clover.com/sdk.js"></script>
</head>

Location of the sdk.js file:

  • Sandbox: https://checkout.sandbox.dev.clover.com/sdk.js
  • Production: https://checkout.clover.com/sdk.js

Configuring the SDK

To make payment requests on a merchant's behalf, set up the SDK to use the merchant's public key retrieved from the PAKMS endpoint.

  1. Create a clover constant and pass the merchant's key as the parameter of a new Clover object.
  2. Declare another constant for clover.elements(). This constant enables you to create card tokens based on information entered in an iframe. Each entity in the iframe is an element.
const clover = new Clover('39c7b87101f44739c823362203d21f89');
const elements = clover.elements();

🚧

IMPORTANT

Apps built for a single merchant can hardcode the public key used to initialize the iframe SDK. If your app is going to be used for more than one merchant, you need to complete the Multi-merchant public key request form.

Setting up the payment form

In this section, you'll create the HTML <form> where a customer enters their credit card information. To set up your payment form, complete the following steps.

  1. Add a <form> to contain card data fields on your page. Set the id attribute to something like payment-form and make a note of this value.
<body>

  <form action="/charge" method="post" id="payment-form">
    <!-- this form contains the card data fields -->
  </form>
 
</body>
  1. In the <form>, create an <input> field to enter the amount of the charge.
<form action="/charge" method="post" id="payment-form">
      
  <div class="form-row top-row">
    <div id="amount" class="field card-number">
      <input name="amount" placeholder="Amount">
    </div>
  </div>
  
</form>
  1. Add <div> containers to enable a user to enter their card details. Following each card data field, add a <div> to display error messages (class="input-errors").
<form action="/charge" method="post" id="payment-form">
  ...
  
  <div class="form-row top-row">
    <div id="amount" class="field card-number">
      <input name="amount" placeholder="Amount">
    </div>
  </div>

  <div class="form-row top-row">
    <div id="card-number" class="field card-number"></div>
    <div class="input-errors" id="card-number-errors" role="alert"></div>
  </div>

  <div class="form-row">
        <div id="card-date" class="field third-width"></div>
        <div class="input-errors" id="card-date-errors" role="alert">
  </div>
  
  <div class="form-row">
        <div id="card-cvv" class="field third-width"></div>
        <div class="input-errors" id="card-cvv-errors" role="alert"></div>
  </div>
    
  <div class="form-row">
        <div id="card-postal-code" class="field third-width"></div>
        <div class="input-errors" id="card-postal-code-errors" role="alert">
    </div>
  </div>
    
  <div id="card-response" role="alert"></div>
    
  ...
</form>
  1. Finally, add a <button> for the user to finalize their payment.
<form action="/charge" method="post" id="payment-form">
  ...
  
  <div class="button-container">
    <button>Submit Payment</button>
  </div>
  
</form>

Adding interaction to the payment form

Once the card entry form is built, make it interactive by connecting it to the JavaScript components provided with the iframe.

  1. Using the <form> element's ID from step one of the previous section, create a constant to access the card entry form.
const form = document.getElementById('payment-form');
  1. Create instances of the card elements and mount them to the <div> containers.

When creating your containers, you can add CSS styling as the second parameter. For more information about CSS styling, see Customizing iframe elements with CSS.

const cardNumber = elements.create('CARD_NUMBER', styles);
const cardDate = elements.create('CARD_DATE', styles);
const cardCvv = elements.create('CARD_CVV', styles);
const cardPostalCode = elements.create('CARD_POSTAL_CODE', styles);
  
cardNumber.mount('#card-number');
cardDate.mount('#card-date');
cardCvv.mount('#card-cvv');
cardPostalCode.mount('#card-postal-code');
  1. Add event listeners for displaying any error messages to the user.

The SDK's real-time validation of the card data fields ensures user entries match the expected format. With the change and blur event listeners, you can handle real-time validation in the iframe.

const cardResponse = document.getElementById('card-response');
const displayCardNumberError = document.getElementById('card-number-errors');
const displayCardDateError = document.getElementById('card-date-errors');
const displayCardCvvError = document.getElementById('card-cvv-errors');
const displayCardPostalCodeError = document.getElementById('card-postal-code-errors');

  // Handle real-time validation errors from the card element
  cardNumber.addEventListener('change', function(event) {
    console.log(`cardNumber changed ${JSON.stringify(event)}`);
  });

  cardNumber.addEventListener('blur', function(event) {
    console.log(`cardNumber blur ${JSON.stringify(event)}`);
  });

  cardDate.addEventListener('change', function(event) {
    console.log(`cardDate changed ${JSON.stringify(event)}`);
  });

  cardDate.addEventListener('blur', function(event) {
    console.log(`cardDate blur ${JSON.stringify(event)}`);
  });

  cardCvv.addEventListener('change', function(event) {
    console.log(`cardCvv changed ${JSON.stringify(event)}`);
  });

cardCvv.addEventListener('blur', function(event) {
    console.log(`cardCvv blur ${JSON.stringify(event)}`);
  });

  cardPostalCode.addEventListener('change', function(event) {
    console.log(`cardPostalCode changed ${JSON.stringify(event)}`);
  });

  cardPostalCode.addEventListener('blur', function(event) {
    console.log(`cardPostalCode blur ${JSON.stringify(event)}`);
  });
{
  "CARD_NUMBER": {
    "error":"Card number is invalid.",
    "touched":true // whether there was any interaction with the field
  },
  "CARD_DATE": {
    "error":"Card expiry is invalid.",
    "touched":true
  },
  "CARD_CVV": {
    "touched":true
  },
  "CARD_POSTAL_CODE": {
    "touched":false
  }
}
  1. Add a listener for the submit event. This listener takes the validated card data from the form and calls clover.createToken().
// Listen for form submission
form.addEventListener('submit', function(event) {
  event.preventDefault();
  // Use the iframe's tokenization method with the user-entered card details
  clover.createToken()
    .then(function(result) {
    if (result.errors) {
      Object.values(result.errors).forEach(function (value) {
        displayError.textContent = value;
      });
    } else {
      cloverTokenHandler(result.token);
    }
  });
});
{
    "token: "clv_1TST39I92..."
}

The returned token needs to be added to the server application to charge the tokenized card.

function cloverTokenHandler(token) {
  // Insert the token ID into the form so it gets submitted to the server
  var form = document.getElementById('payment-form');
  var hiddenInput = document.createElement('input');
  hiddenInput.setAttribute('type', 'hidden');
  hiddenInput.setAttribute('name', 'cloverToken');
  hiddenInput.setAttribute('value', token);
  form.appendChild(hiddenInput);
  form.submit();
}

Creating a charge

Once the token is returned, send the amount and the token (as the value of source) to the /v1/charges endpoint to complete the transaction. Set the authorization: Bearer as your OAuth-generated auth_token.

Because of CORS restrictions, this request must be a server-to-server call as shown in the diagram at the beginning of this topic.

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/charges \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {auth_token}' \
  --header 'content-type: application/json' \
  --data '{"amount":4500,"currency":"usd","source":"clv_1TSTS778rnkeDPBiFRZc4zuD"}'

The charge is processed for the specified amount using the token.

Updated 28 days ago


Using the Clover-hosted iframe


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.