Install Checkout Components for Web

Install the Web SDK library and start using components in your project.

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 your API credentials

In order to initialise the SDK, you'll need to send authenticated requests to the PXP API.

To get your credentials:

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select a merchant group.
  3. Click the Inbound calls tab.
  4. Copy the Client ID in the top-right corner.
  5. Click New token.
  6. Choose a number of days before token expiry. For example, 30.
  7. Click Save to confirm. Your token is now created.
  8. Copy the token ID and token value. Make sure to keep these confidential to protect the integrity of your authentication process.
📘

As best practice, we recommend regularly generating and implementing new tokens.

Step 3: Get the session data

Now that you have your credentials, you can send an API request to the sessions endpoint. This allows you to retrieve the transaction session data from the back-end, so you can supply it when you initialise the SDK.

curl -i -X POST \
  'https://api-services.test.pxpfinancial.com/v1/sessions' \
  -H 'Authorization: PXP-UST1 {tokenId}:{timestamp}:{hmac}' \
  -H 'X-Request-Id: {requestId}' \
  -H 'X-Client-Id: {clientId}' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "TRANSACTION-1",
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  }
}'

Header parameters

Our platform uses HMAC (Hash-based Message Authentication Code) with SHA256 for authentication to ensure secure communication and data integrity. This method involves creating a signature by hashing your request data with a secret key, which must then be included in the HTTP headers of your API request.

To authenticate, you'll need to:

  • Create a unique request ID (UUID or GUID) for each API request.
  • Use your token value and request details to create an HMAC signature with cryptographic functions.
Header nameDescriptionFormat
Authorization HeaderThe HMAC signature. This is made up of the authentication scheme, (e.g., PXP-UST1), your tokenId, the timestamp, and the HMAC value."Authorization: PXP-UST1 {tokenId}:{timestamp}:{hmac}"
X-Request-Id HeaderThe unique request ID that you generated."X-Request-Id: {requestId}"
X-Client-Id HeaderYour clientId , which identifies your specific client application."X-Client-Id: {clientId}"

Body parameters

ParameterDescription
merchant
string (≤ 20 characters)
required
Your unique merchant identifier, as assigned by PXP. This is supplied to you during onboarding.
site
string (≤ 20 characters)
required
Your unique site identifier, as assigned by PXP. This is supplied to you during onboarding.
merchantTransactionId
string (≤ 50 characters)
required
A unique identifier of your choice that represents 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. See Supported payment currencies.
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": {}
    }
  }
}
ParameterDescription
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 4: 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, 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_0`",
      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
string
required

The environment type.

Possible values:

  • test
  • live

session
sessionData
required

Details about the checkout session.

ownerId
string
required

The identifier of the owner related to the ownerType.

ownerType
string
required

The type of owner.

Possible values:

  • MerchantGroup
  • Merchant
  • Site

merchantShopperId
string
required

A unique identifier for this shopper.

transactionData
object
required

Details about the transaction.

transactionData.currency
string (1-3 characters)
required

The currency code associated with the transaction, in ISO 4217 format.

transactionData.amount
number

The transaction amount.

transactionData.entryType
string
required

The entry type.

Possible values:

  • Ecom
  • MOTO

transactionData.intent
string
required

The transaction intent. Learn more about intents.


Possible values:

  • Authorisation
  • EstimatedAuthorisation
  • Purchase
  • Payout
  • Verification

transactionData.merchantTransactionId
string
required

A unique identifier for this transaction.

transactionData.merchantTransactionDate
string
required

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.

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).