Step 1: Install the Web SDK library

To get started, install the latest version of the Web SDK from the npm public registry. You'll need to have Node.js 22.x or higher.

npm i @ pxpio/web-components-sdk

Step 2: Get the session data

You'll need to supply the transaction session data when you initialise the SDK.

To retrieve it from the back-end, send an API request to the sessions endpoint:

curl --request POST \
     --url https://api-services.test.pxpfinancial.com/v1/sessions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "TRANSACTION-1",
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  }
}
'

Parameter	Description
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP.
`merchantTransactionId` string (≤ 50 characters) required	A unique identifier for this transaction.
`sessionTimeout` number required	The duration of the session, in minutes.
`amounts` object required	Details about the transaction amount.
`amounts.currencyCode` string (3 characters) required	The currency code associated with the transaction, in ISO 4217 format.
`amounts.transactionValue` number required	The transaction amount. The numbers after the decimal will be zero padded if they are less than the expected `currencyCode` exponent. For example, GBP 1.1 = GBP 1.10, EUR 1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected if numbers after the decimal are greater than the expected `currencyCode` exponent (e.g., GBP 1.234), or if a decimal is supplied when the `currencyCode` of the exponent does not require it (e.g., JPY 1.0).

If your request is successful, you'll receive a 200 response containing the session data.

{
  "sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
  "hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
  "encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
  "sessionExpiry": "2025-05-19T13:39:20.3843454Z",
  "allowedFundingTypes": {
    "cards": [
      "Visa",
      "Diners",
      "Mastercard",
      "AmericanExpress"
    ],
    "wallets": {
      "paypal": {
        "allowedFundingOptions": [
          "venmo", 
          "paylater", 
          "paypal"
        ]
      },
      "applepay": {}
    }
  }
}

Parameter	Description
`sessionId` string (UUID)	The unique identifier for the newly-created session.
`hmacKey` string	The HMAC key generated for securing session communications.
`encryptionKey` string	A key used for encrypting sensitive session data during communication.
`sessionExpiry` string	The timestamp indicating when the session will expire, in ISO 8601 format.
`allowedFundingTypes` object	Details about the funding types allowed for this session. Possible values: `cards` `wallets`
`allowedFundingTypes.cards` array of strings or null	The list of supported card schemes.
`allowedFundingTypes.wallets` array of strings or null	The list of supported wallets.

Step 3: Initialise the SDK

To initialise the SDK, you then need to pass this session data back to the front-end.

You'll also need to provide details about the environment you're using, your owner ID and type, the merchant shopper ID, the transaction data, and the shipping data.

import { PxpCheckout } from "@pxpio/web-components-sdk";
import NewCardComponent from "@pxpio/web-components-sdk/src/components/newCardComponents/NewCardComponent";
import CurrencyType from "@pxpio/web-components-sdk/src/pxpCheckouts/types/CurrencyType";
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_09",
      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>
  </>;
}

Property	Description
`environment` stringrequired	The environment type. Possible values: `test` `live`
`session` sessionDatarequired	Details about the checkout session.
`ownerId` stringrequired	The identifier of the owner related to the `ownerType`.
`ownerType` stringrequired	The type of owner. Possible values: `MerchantGroup` `Merchant` `Site`
`merchantShopperId` stringrequired	A unique identifier for this shopper.
`transactionData` objectrequired	Details about the transaction.
`transactionData.currency` string (1-3 characters)	The currency code associated with the transaction, in ISO 4217 format.
`transactionData.amount` requirednumber	The transaction amount.
`transactionData.entryType` stringrequired	The entry type. Possible values: `Ecom` `MOTO`
`transactionData.intent` stringrequired	The transaction intent. Learn more about intents. Possible values: `Authorisation` `EstimatedAuthorisation` `Purchase` `Payout` `Verification`
`transactionData.merchantTransactionId` stringrequired	A unique identifier for this transaction.
`transactionData.merchantTransactionDate` stringrequired	The date and time of the transaction, in ISO 8601 format.
`shippingAddress` object	Details about the shipping address.
`shippingAddress.address` string	The first line of the shipping address.
`shippingAddress.addressLine2` string	The second line of the shipping address.
`shippingAddress.city` string	The city of the shipping address.
`shippingAddress.postalCode` string	The postal or ZIP code of the shipping address.
`shippingAddress.countryCode` string (2 characters)	The country code of the shipping address, in ISO-3166-1 alpha-2 format.
`analyticsEvent: analyticsEventHandler`	Handler for analytics events.

Step 4: Create and customise a component

You can now go ahead and create a component in your project. In this example, we're using the new card component. You can view a full list of customisation options in the NewCardComponentConfig reference.

const [newCardComponent, setNewCardComponent] = useState<NewCardComponent>();

  useEffect(() => {
    // Create and customise components
    setNewCardComponent(pxpCheckoutSdk.create('new-card') as NewCardComponent);
  }, []);

  useEffect(() => {
    // Mount the new card component
    newCardComponent?.mount('new-card-container');
    return () => {
      // Unmount the new card component
      newCardComponent?.unmount();
    }
  }, [newCardComponent]);

  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>
  </>;
}

That's it! You've got your first card component up and running. For more information about the other available components and some visual examples, check out the Pre-built components and Standalone components sections.

ℹ️
When you're ready to go live, make sure to update the sandbox URLs to production instead (https://api-services.pxpfinancial.com).