npm package: @pxpio/web-components-sdk
Description: <img src="https://files.readme.io/8b472a7a02afbfa6889aa00c54343cf7fe3f97efdeb0a6d1258816be60f35892-pxp-banner1.jpg" alt="PXP banner" style="max-width:100%"><br />
Latest version: 2.1.6

<img src="https://files.readme.io/8b472a7a02afbfa6889aa00c54343cf7fe3f97efdeb0a6d1258816be60f35892-pxp-banner1.jpg" alt="PXP banner" style="max-width:100%"><br />

# Checkout Components for Web

Checkout Components allow you to easily build a frictionless checkout experience for your customers. Our fast, secure, and seamless payment components are pieces of the checkout journey that can be integrated to customise, personalise, and expand checkout capabilities. 

<center>
<img src="https://files.readme.io/8341e3a3fea309ae7a39943a42f151e03ed962378deb4ab3d6f40474e3802039-Shopping_cart.svg" alt="Example of a checkout using Checkout Components." style="max-width:100%">
</center>

Components are currently available for:
- **Card:** Visa, Mastercard, Amex, Discover, Diners, CUP, and JCB.
- **PayPal:** PayPal, Venmo, and PayPal Pay later.

Additional support for Apple Pay is coming soon.


## Features

* **Unmatched customisability:** Tailor the entire checkout experience to match your brand's look and feel, without limitations.
* **Streamlined integration:** Our developer-friendly SDK is easy to integrate into your checkout and gives you full control over the design and function, with the flexibility to scale as needed.
* **Flexible analytics:** Track user behaviour and get deeper insights than with rigid Google Analytics setups, thanks to custom events that can be used with your analytics tool of choice.
* **Scalable and secure transactions:** We're PCI DSS compliant, with 3DS integration and secure tokenisation for every transaction.
* **Flexible component rendering:** Skip rendering certain components entirely and provide your own, while still using PXP’s secure backend to collect information.
* **Future-ready technology:** Stay up-to-date with the latest technologies with ongoing updates, including support for card wallets and multilingual features.

## Integration process

1. Set up the relevant Checkout services in the Unity Portal.
2. Install the latest version of the SDK.
3. Initialise the SDK. 
4. Create and mount your components.
5. Add proper handling for events and errors.
6. Submit and view transactions.

## Pre-requisites

- PXP account and <a href="https://developer.pxp.io/docs/activate-component-services#/" target="_blank">activated Checkout services</a>.
- Node.js 22.x or higher.

## Installation

Run this command to install the library:
```Shell
npm i @ pxpio/web-components-sdk
```

## Initialisation

To initialise the SDK, you'll need to send a request to the PXP Sessions endpoint and then pass that data back to the front-end. 
<a href="https://developer.pxp.io/docs/install-checkout-components-for-web#/" target="blank">This guide takes you through all the required steps.</a>

Here's an example of the new card component being initialised, created, and mounted.

```
import { PxpCheckout, NewCardComponent, CurrencyType } from "@pxpio/web-components-sdk";
import { useEffect, useState } from "react";

export default function CreateComponent() {
  const [pxpCheckout, setPxpCheckout] = useState<PxpCheckout>();
  const [newCardComponent, setNewCardComponent] = useState<NewCardComponent>();

  useEffect(() => {
    initialiseTheSdkAsync();
  }, []);

  useEffect(() => {
    // Create and customise components
    setNewCardComponent(pxpCheckout.create("new-card") as NewCardComponent);
  }, [pxpCheckout]);

  useEffect(() => {
    // Mount the new card component
    newCardComponent?.mount("new-card-container");
    return () => {
      // Unmount the new card component
      newCardComponent?.unmount();
    }
  }, [newCardComponent]);

  async function initialiseTheSdkAsync() {
    // 1. Get the session data from the back-end
    const sessionData = await getSessionDataFromBEAsync();

    // 2. Initialise the SDK
    const pxpCheckoutSdk = PxpCheckout.initialize({
      environment: "test",
      session: sessionData,
      ownerId: "Unity",
      ownerType: "MerchantGroup",
      merchantShopperId: "Shopper_01",
      transactionData: {
        currency: "USD" as CurrencyType,
        amount: 25,
        entryType: "Ecom",
        intent: "Authorisation",
        merchantTransactionId: crypto.randomUUID(),
        merchantTransactionDate: () => new Date().toISOString(),
      },
    });

     setPxpCheckout(pxpCheckoutSdk);
  }

  return <>
    <h1 className="text-center">Init SDK</h1>
    <div className="d-flex justify-content-center">
      <div id="new-card-container" style={{ width: "400px" }}></div>
    </div>
  </>;
}
```

## Implementation

Every component follows the same basic three-step lifecycle:
1. Create the component and optionally add your own configuration. For example, you can implement analytics to monitor your customers' payment journeys.
2. Mount the component. This is what makes the component visible and interactive.
3. Unmount the component. This is a clean-up step that clears up resources.

To learn how to implement components, see:
* <a href="https://developer.pxp.io/docs/card-components-implementation#/" target="_blank">Card implementation</a>
* <a href="https://developer.pxp.io/docs/paypal-component-implementation#/" target="_blank">PayPal implemtnation</a>

## Customisation

All components come with responsive and accessible default styling, but are designed to be customisable. 

To learn how to customise the look and feel of components, see:
* <a href="https://developer.pxp.io/docs/about-card-components-customisation#/" target="_blank">Card customisation</a>
* <a href="https://developer.pxp.io/docs/customise-paypal-component#/" target="_blank">PayPal customisation</a>

## Support

If you have any questions or concerns, reach out to our support team at [support@pxp.io](mailto:support@pxp.io).