xendit-components-web

With Xendit Components, you can build a checkout experience tightly integrated into your site, powered by the Xendit Sessions API.

This SDK provides UI components for payment method selection, user input (e.g. credit cards), and user actions (e.g. 3DS), all of which can be customized to match your site's look & feel.

View a live demo here by choosing "Xendit Components". View the demo source code here.

Installation

Install using npm:

npm install xendit-components-web --save

Or load it directly from our CDN:

<script src="https://assets.xendit.co/components/v0.0.22/index.umd.js"></script>

Our npm package includes TypeScript types. You also download the .d.ts file directly.

Sessions

The Xendit Session API is an abstraction over the Xendit Payments API, representing one transaction (or tokenization). Using one session, a user can make any number of attempts to pay, one of which can be successful. A successful payment completes the session.

Sessions also abstract away any differences between channels, allowing you to write once, and accept payments from any channel Xendit supports.

Two types of sessions are available:

• PAY sessions collect a payment and optionally save a payment token for later use
• SAVE sessions save a payment token

Quick Start

First, initialize the SDK either with either:

• Use XenditComponentsTest to use mock payment methods for development and testing.
• Use XenditComponents to connect to the Xendit backend (including Xendit's test mode). This requires a componentsSdkKey option, which you can get by calling the Create Session endpoint. Create a session from your server, passing the components_sdk_key property back to your frontend.

// For frontend development, use XenditComponentsTest, this provides built-in mock payment methods
const components: XenditComponents = new XenditComponentsTest({});
// For production or e2e testing, use XenditComponents, passing in the components_sdk_key from the Session object
const components: XenditComponents = new XenditComponents({ componentsSdkKey });

// Create a channel picker component
const channelPicker: HTMLElement = components.createChannelPickerComponent();

// Insert the channel picker into your document
myCheckoutPage.replaceChildren(channelPicker);

// Call submit() when the user clicks your submit button
mySubmitButton.addEventListener("click", () => {
  components.submit();
});

// Listen to the status of the session
components.addEventListener("session-complete", () => {
  alert("Payment Success");
});
components.addEventListener("session-expired-or-canceled", () => {
  alert("Payment cancelled or expired");
});

Components API

XenditComponents and XenditComponentsTest

Constructor functions.

Both have the same API. XenditComponents will connect to Xendit servers, while XenditComponentsTest provides mock payment channels.

createChannelPickerComponent

const htmlElement = components.createChannelPickerComponent();
myContainer.replaceChildren(htmlElement);

Creates a UI for the user to select a payment channel and fill any required information.

This returns a HTMLElement, which you need to insert into your document.

This method uses caching, it will always return the same channel picker element. Changing the current channel will update the channel picker UI, even if it's unmounted. If you don't want this, use destroyComponent.

getActiveChannels

const channels = components.getActiveChannels();

Returns the list of channels available in this session.

getActiveChannelGroups

const groups = components.getActiveChannelGroups();

Returns a list of channel groups. This can be used to categorize channels by type, if you want to build your own channel selection UI. Each channel has a uiGroup property which matches one group's id property.

createChannelComponent

const channel = components.getActiveChannels({ filter: "CARDS" })[0];
if (channel) {
  const htmlElement = components.createChannelComponent(channel);
  myContainer.replaceChildren(htmlElement);
}

Selects a payment channel and creates a UI for the user to fill any required information. You need to pass in the channel you want to use, as returned from getActiveChannels.

This returns a HTMLElement, which you need to insert into your document.

This method uses caching, it will always return the same element for the same channel, to preserve the values the user enters into any form fields. If you don't want that, use destroyComponent.

createActionContainerComponent

components.addEventListener("action-begin", () => {
  const htmlElement = components.createActionContainerComponent({
    qrCode: {
      qrCodeOnly: true,
    },
  });
  myActionContainer.replaceChildren(htmlElement);
});

Creates a container into which any additional actions (e.g. 3DS, QR Codes) will be rendered.

This is optional, if you don't create one, the SDK will create a modal with an action container for you. You cannot create an action container during an action (i.e. after the action-begin event).

This returns a HTMLElement, which you need to insert into your document.

This method does not use caching.

submit

function onSubmitButtonClick() {
  components.submit();
}

Begins submission for the active payment channel.

Call this from the click event of your submit button.

Submission is only available when the session is active, a channel is made current by creating a channel component, any required information is collected, and another submission is not in progress. Use the submission-ready and submission-not-ready events to know when submission is available.

This calls the create payment request or create payment token endpoint depending on the session type. You may listen to the corresponding webhooks on your server.

simulatePayment

components.simulatePayment();

Calls the simulate payment endpoint.

This is only available in test mode sessions. It also requires the payment channel to be a QR, OTC, or VA channel, and it requires an action to be in-progress.

abortSubmission

components.abortSubmission();

Cancels the current submission, if any.

destroyComponent

components.destroyComponent(htmlElement);

Destroys a component, deleting any cached data and removing the element from the document. Manual cleanup is not normally required, but is made available if you want it.

showValidationErrors

components.showValidationErrors();

Reveals hidden validation errors in the current channel's form, if any.

Validation errors are normally hidden until the user changes and unfocusses the input.

getCurrentChannel

const channel: XenditChannel = components.getCurrentChannel();

Returns the current channel.

The current channel is the one you or the channel picker component selected by calling createChannelComponent or setCurrentChannel.

The current channel:

• Will be used for submission when you call submit()
• Is interactive (other channel components are disabled)

setCurrentChannel

const channel = components.getActiveChannels({ filter: "CARDS" })[0];
if (channel) {
  components.setCurrentChannel(channel);
}

Makes the provided channel the current channel.

pollImmediately

components.pollImmediately();

Immediately poll for the status of a submission. Only applicable while a submission is ongoing. Useful for handling payment affirmation (e.g. I have made the payment) by the user.

Events

init

Notifies you when the session information is loaded. Most SDK functions require the session to be loaded and can only be called after this event.

createChannelPickerComponent is available before the init event.

session-complete and session-expired-or-canceled

Notifies you when the session is in a terminal state.

session-complete means the session was successful, session-expired-or-canceled means the session was cancelled or expired.

session-pending and session-not-pending

Notifies you when the session is in the pending state. The pending state means a payment request or token will take some time to complete due to a manual approval flow. This affects FPX business payments. No other payment attempts can be made while in the pending state.

You might want to show a pending state UI when in the pending state.

submission-ready and submission-not-ready

Notifies you when the user is ready to submit the payment, meaning a channel is selected and all required information is collected.

submit will only work in the ready state, or it will throw. Calling it when there are form validation errors will also reveal those errors to the user.

You might want to disable your submit button when not in the ready state.

submission-begin and submission-end

Notifies you when a submission is in progress.

You might want to show a pending state UI when in the submission state, and allowing the action UI to show on top.

action-begin and action-end

Notifies you when an action is in progress.

Optionally, you can create an action container in the action-begin event. A default action container modal will be created if you don't.

Appearance

CSS

The Xendit Components SDK is designed to be customized with CSS. You can override any styles with your own CSS. The SDK's base is inserted above other stylesheets at the time of loading to allow it to be easily overridden.

Refer to styles.css for all the overidable selectors.

CSS Variables

Some CSS variables are provided to allow for easy customization. These are defined on :root and can be overridden by your own CSS.

The following variables are available: | Variable | Description | | :- | :- | | --xendit-font-family | Font applied to all xendit components | | --xendit-color-primary | Accent color | | --xendit-color-text | Base text color | | --xendit-color-text-secondary | Lighter text color | | --xendit-color-text-placeholder | Placeholder color | | --xendit-color-disabled | Background color of disabled elements | | --xendit-color-danger | Border color of elements with validation errors and text color of validation errors | | --xendit-color-border | Border color used on accordions, input fields, and logos | | --xendit-color-background | Background color of input fields | | --xendit-focus-shadow | Box-shadow applied to elements with focus | | --xendit-animation-duration | Duration of animations (affects the channel picker accordion) | | --xendit-animation-ease | Ease function of animations | | --xendit-radius-1 | Border radius applied to some components | | --xendit-z-index-focus | Z-index applied to focused fields | | --xendit-qr-foreground-color | The color used for QR codes (the black pixels). | | --xendit-qr-background-color | The color used as the background of QR codes (the white pixels). |

Additionally, the following variables are set at component scope, where applicable: | Variable | Description | | :- | :- | | --xendit-channel-brand-color | A brand color. Varies depending on the channel or action component where it's used. Will always be a dark color appropriate for use as a background behind white text. |

CSS In Iframe Fields

Some form fields (credit card inputs) are implemented inside iframes to protect the user's information.

You can't override the CSS inside the iframe fields. Instead, you can pass some limited styles to the constructor which we'll pass along to the iframes.

const sdk = new XenditComponents({
  iframeFieldAppearance: {
    inputStyles: {
      // apply styles to inputs within iframe fields
      color: "#000",
    },
    placeholderStyles: {
      // apply styles to input placeholders in iframe fields
      color: "#ccc",
    },
  },
});

Fonts In Iframe Fields

Iframes can't inherit fonts you define on your page, so we allow you to load the font separately inside the iframe, by passing the font source to the constructor.

const sdk = new XenditComponents({
  iframeFieldAppearance: {
    inputStyles: {
      // fontFamily: "serif", // this is ignored if a fontFace is provided
    }
    fontFace: {
      // insert a @font-face rule inside iframe fields
      source: "url(https://example.com/my-font-file) format(woff2)",
      descriptors: { display: "swap" },
    },
  },
});

Troubleshooting

Usage with React Strict Mode

Since React 18, Strict Mode will perform mount/unmount checks during development. This means React intentionally unmounts and remounts every component on its initial mount.

If you instantiate XenditComponents and add a listener for the init event in a side effect, this can cause a race condition where the event fires for the last instance before the first instance finishes mounting. Hence, you should remember to remove the init event listener in the effect cleanup function when Strict Mode is on.

useEffect(() => {
  // ...
  const handleInit = () => {
    // ...
  };
  components.addEventListener("init", handleInit);
  return () => {
    components.removeEventListener("init", handleInit);
  };
}, []);