Integration Guide

This guide provides a detailed, step-by-step process for integrating Smart Fields into your payment checkout. By the end, you will be able to securely collect payment details directly within your website while Localpayment handles the sensitive data.

Prerequisites

Before you begin the integration, ensure you have the following:

• API Keys: A valid API key for authenticating requests. You can use a key from either the Stage or Production environment, depending on your development phase.

• Client Code: Your unique client identifier, found in your Localpayment dashboard.

• Backend Endpoint: Your server must be prepared to receive a payment token from your frontend and use it to execute a transaction via the Localpayment Payins API.

Step 1: Include the Smart Fields SDK

Add the Localpayment SDK to your website by including the appropriate script tag for your environment. We provide two different environments to support your development workflow:

Stage Environment

Use this for testing and development before going live. This environment allows you to test with simulated payments and validate your integration.

<script src="https://sdk.stage.localpayment.com/localpayment-sdk.min.js"></script>

Production Environment

Step 2: Initialize the SDK

After successfully including the SDK, initialize it with your unique credentials. The LP constructor requires both your client code and API key to authenticate requests and configure the SDK properly.

Basic Initialization

const localpayment = LP({
    clientCode: 'your_client_code', // Your client code here 
    apiKey: 'your_api_key' // Your secret API key for authentication
});

Configuration Options

Parameter	Type	Required	Description
clientCode	string	Yes	Your unique merchant identifier provided by Localpayment
apiKey	string	Yes	Your secret API key for authentication requests

Step 3: Create a Session

Before creating payment fields, you must create a session. This step establishes a secure connection with Localpayment's servers and prepares the environment for card tokenization.

await localpayment.createSession();

Step 4: Create and Mount the Payment Fields

After initializing your session, the next step is to create and mount the payment fields.

Creating Payment Fields

Use the create() method to instantiate each payment field. The method accepts a single parameter fieldType which must be one of three values: 'pan', 'cvv', or 'expiration'.

// Create individual payment fields
const panField = localpayment.create('pan'); // Card number field
const cvvField = localpayment.create('cvv'); // Security code field
const expirationField = localpayment.create('expiration'); // Expiration date field

Field Types Overview

Field Type	Purpose	Validation Features
pan	Primary Account Number (card number)	Luhn algorithm, brand detection, format validation
cvv	Card Verification Value	Length validation (3-4 digits), numeric only
expiration	Expiration date	MM/YY format, future date validation

Mounting Fields to DOM

The mount() method attaches the secure iframe to your specified DOM container. The method accepts a selector string that should match the id of your container div.

HTML Container Setup

First, create container elements in your HTML:

<div class="form-group">
    <label for="pan-container">Card Number</label>
    <div id="pan-container"></div>
    <div class="error-message" id="pan-error"></div>
</div>

<div class="form-group">
    <label for="cvv-container">CVV</label>
    <div id="cvv-container"></div>
    <div class="error-message" id="cvv-error"></div>
</div>

<div class="form-group">
    <label for="expiration-container">Expiration Date</label>
    <div id="expiration-container"></div>
    <div class="error-message" id="expiration-error"></div>
</div>

Mounting the Fields

// Mount each field to its respective container
panField.mount('#pan-container');
cvvField.mount('#cvv-container');
expirationField.mount('#expiration-container');

Step 5: Handle Field Events and Validation

Listen to events from each field to update your UI and track their validation status.

// Example: Listen for changes on the card number field
panField.on('change', (state) => {
    // state contains: isValid, isEmpty, isFocused, error
    if (state.isValid) {
        // Field is valid, update UI accordingly
    } else if (state.error) {
        // Show error message to user
        console.error(state.error);
    }
});

Step 6: Get Session Data

Retrieve the session data and sessionId.

const sessionData = localpayment.getSessionData(); // Contains sessionId, accessToken, clientCode.
console.log(sessionData.sessionId);

Step 7: Consolidate Session

Make a POST request to the Consolidate endpoint, sending the sessionId and cardholder details.

• Stage: https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate

• Production: https://tokenization.api.localpayment.com/api/tokenization/consolidate

const response = await fetch('https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientCode: 'your_client_code',
    sessionId: sessionData.sessionId,
    CardholderName: 'John Doe'
  })
});

const consolidationResult = await response.json();
console.log(consolidationResult);

Step 8. Use the Token

The consolidate response includes the token and card metadata (bin, brand, last4, expiration).

Your frontend should send this token to your backend, which will use it to call the Payins API and process the payment.

Example response:

{
    "token": "lnZB3Rq1sbCB9sZnxgqtxbcPUR49G3I1tl%2BBsbt2vaM%3D",
    "bin": "424242",
    "brand": "VISA",
    "country": "GB",
    "name": "John Doe",
    "last4": "4242",
    "expirationYear": 2029,
    "expirationMonth": 11
}