API Reference

This document provides a complete technical reference for the Smart Fields SDK, including methods, events, and configuration options.

Constructor

Use the LP constructor to create an SDK instance in your application. This must be called before any other methods.

const localpayment = LP({
  clientCode: 'your_client_code',
  apiKey: 'your_api_key'
});

Parameter	Type	Required	Description
clientCode	String	Yes	Your unique client identifier provided by Localpayment.
apiKey	String	Yes	The API key generated in your Localpayment Dashboard (stage or prod).

Methods

createSession()

Creates a new session with the Localpayment backend. This session is valid for a limited time (10 minutes) and must be created before mounting any payment fields.

• Returns: Promise<void>

• Throws: An error if the network request fails or the credentials are invalid.

Example:

try {
    await localpayment.createSession();
    console.log('Session created successfully');
} catch (error) {
    console.error('Failed to create session:', error);
}

create(fieldType)

Creates an instance of a secure payment field. The field is not visible until it is mounted.

Parameters:

Parameter	Type	Required	Description
fieldType	String	Yes	The type of field to create. Accepted values: 'pan', 'cvv', 'expiration'.

• Returns: LPField instance.

Example:

// Create field instances
const panField = localpayment.create('pan');
const cvvField = localpayment.create('cvv');
const expirationField = localpayment.create('expiration');

getSessionData()

Retrieves the data for the current active session, including the session ID and access token. This is essential for the token consolidation step on your backend.

• Returns: Object containing session data.

  • sessionId (String): The unique identifier for the current session.

  • accessToken (String): The short-lived token used for authenticating the consolidation request.

  • clientCode (String): The client code used to initialize the SDK.

  • apiKey (String): The API key used to initialize the SDK.

Example:

const sessionData = localpayment.getSessionData();
// Example response: { sessionId: 'd069f375-c07c-4ac8-9f8a-6abbeb31f459', accessToken: 'eyJhbGci...', clientCode: '0001', apiKey: 'IIBCgKCAQEAtI...' }

---

Field Instance Methods

After creating a field with localpayment.create(), you can use the following methods on the returned object.

Method	Description	Example
mount(selector)	Mounts the field's iframe into the specified DOM container.	panField.mount('#card-number-container');
unmount()	Removes the field's iframe from the DOM.	panField.unmount();
clear()	Clears the current value from the field.	panField.clear();
focus()	Sets the focus into the field.	panField.focus();
blur()	Removes the focus from the field.	panField.blur();
on(event, callback)	Registers a callback function for a specific event on this field.	panField.on('change', (state) => { ... });

---

Field Types

The following field types are available to create using the create() method.

Field Type	create() Parameter	Description	Example Output
Card Number	'pan'	Input for the primary account number (PAN). Automatically formats and spaces the number.	4111 1111 1111 1111
Security Code	'cvv'	Input for the card verification value (CVV/CVC).	123
Expiration Date	'expiration'	Input for the card's expiration date. Uses MM-YYYY format.	12-2028

---

Events

Listen to events on a field instance using the .on() method to react to state changes.

'change' Event

Triggered when the field's value or validation state changes.

Callback receives: state (Object)

• state.isEmpty (Boolean): true if the field has no value.

• state.isValid (Boolean): true if the current value is valid.

• state.isFocused (Boolean): true if the field currently has focus.

• state.error (String | undefined): A string describing the validation error, if any.

Example:

panField.on('change', (state) => {
    if (state.isValid) {
        // Update UI to show valid state
        console.log('Card number is valid');
    } else if (state.error) {
        // Update UI to show error message
        console.error('Validation error:', state.error);
    }
});

'tokenized' Event

Triggered when the field's value has been successfully tokenized by the Localpayment backend. This usually happens after a valid value is entered and the field loses focus.

Example:

panField.on('tokenized', (token) => {
    console.log('PAN tokenized with token:', token);
    // You can track that this field is ready for consolidation
});

'error' Event

Triggered when a non-recoverable error occurs, such as a tokenization failure.

Callback receives: error (Object)

• error.error (String): A general error message.

• error.metadata (Object | undefined): Additional metadata about the error.

Example:

panField.on('error', (error) => {
    console.error('An error occurred:', error.error);
    if (error.metadata) {
        console.error('Error details:', error.metadata);
    }
});

---

Error Handling

The SDK provides errors through the 'error' event and rejected promises. Common error scenarios include:

• Network Errors: createSession() will fail if a network request cannot be made.

• Invalid Credentials: createSession() will fail if the clientCode or apiKey is incorrect.

• Tokenization Errors: The 'error' event will fire if a field's value cannot be tokenized (e.g., an invalid card number that passes basic validation but is rejected by the processor).

• Session Expiration: Operations will fail if the session has expired. You must catch this and typically recreate the session.

Example of comprehensive error handling:

// Handle field errors
panField.on('error', (error) => {
    showUserError(`Card number error: ${error.error}`);
});

// Handle session creation errors
try {
    await localpayment.createSession();
} catch (error) {
    console.error('Session creation failed. Please check your credentials.', error);
}