API Reference
GuidesAPI ReferenceGo to DashboardSite >
Start typing to search…

The Fields Object

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

MethodDescriptionExample
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 Typecreate() ParameterDescriptionExample 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);
}