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:
- In the Unity Portal, go to Merchant setup > Merchant groups.
- Select a merchant group.
- Click the Inbound calls tab.
- Copy the Client ID in the top-right corner.
- Click New token.
- Choose a number of days before token expiry. For example,
30
. - Click Save to confirm. Your token is now created.
- 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 name | Description | Format |
---|---|---|
Authorization Header | The 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 Header | The unique request ID that you generated. | "X-Request-Id: {requestId}" |
X-Client-Id Header | Your clientId , which identifies your specific client application. | "X-Client-Id: {clientId}" |
Body parameters
Parameter | Description |
---|---|
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": {}
}
}
}
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:
|
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 |
---|---|
| The environment type.
|
| Details about the checkout session. |
| The identifier of the owner related to the |
| The type of owner.
|
| A unique identifier for this shopper. |
| Details about the transaction. |
| The currency code associated with the transaction, in ISO 4217 format. |
| The transaction amount. |
| The entry type.
|
| The transaction intent. Learn more about intents.
|
| A unique identifier for this transaction. |
| The date and time of the transaction, in ISO 8601 format. |
| Details about the shipping address. |
| The first line of the shipping address. |
| The second line of the shipping address. |
| The city of the shipping address. |
| The postal or ZIP code of the shipping address. |
| The country code of the shipping address, in ISO-3166-1 alpha-2 format. |
| 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
).
Updated about 18 hours ago