# Installation

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.


```shell
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're ready to 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.

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.

### Create an HMAC signature

To create the HMAC signature, you need to prepare a string that includes four parts:

* A timestamp,  in Unix format. For example, `1754701373`.
* A unique request ID, in GUID format. For example, `ce244054-b372-42c2-9102-f0d976db69f6`.
* The request path, which is `api/v1/sessions`.
* The request body. For example:

```json
{
   "merchant": "MERCHANT-1",
   "site": "SITE-1",
   "sessionTimeout": 120,
   "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
   "transactionMethod": {
     "intent": {
       "card": "Authorisation",
       "paypal": "Purchase"
     }
   },
   "amounts": {
     "currencyCode": "EUR",
     "transactionValue": 20
   },
   "allowTransaction": true,
   "addressVerification": {
     "countryCode": "GB",
     "houseNumberOrName": "10 Downing Street",
     "postalCode": "SW1A 2AA"
   },
   "identityVerification": {
     "nameVerification": true
   },
   "threeDSecureData": {
     "threeDSecureVersion": "2.2",
     "electronicCommerceIndicator": "05",
     "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
     "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
     "threeDSecureTransactionStatus": "Y"
   }
}
```


| Parameter | Description |
|  --- | --- |
| `merchant`string (≤ 20 characters) | Your unique merchant identifier, as assigned by PXP. You can find it in the Unity Portal, by going to **Merchant setup > Merchants** and checking the *Merchant ID* column or by clicking on a merchant and checking the *General information* section. |
| `site`string (≤ 20 characters) | Your unique site identifier, as assigned by PXP. You can find it in the Unity Portal, by going to **Merchant setup > Sites** and checking the *Site ID* column or by clicking on a site and checking the *General information* section. |
| `merchantTransactionId`string (≤ 50 characters) | A unique identifier of your choice that represents this transaction. |
| `sessionTimeout`number | The duration of the session, in minutes. |
| `transactionMethod`object | Details about the transaction method, including the intent for each payment type. |
| `transactionMethod.intent`object | The transaction intent for each payment method. |
| `transactionMethod.intent.card`string | The intent for card, Apple Pay, or Google Pay transactions.Possible values:`Authorisation``Purchase``Verification``EstimatedAuthorisation``Payout` |
| `transactionMethod.intent.paypal`string | The intent for PayPal transactions.Possible values:`Authorisation``Purchase``Payout` |
| `amounts`object | Details about the transaction amount. |
| `amounts.currencyCode`string (3 characters) | The currency code associated with the transaction, in ISO 4217 format. See [Supported payment currencies](/guides/components/supported-currencies). |
| `amounts.transactionValue`number | 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). |


#### Extended parameters

The following optional parameters can be included in your session request to enable additional verification and security features.

| Parameter | Description |
|  --- | --- |
| `allowTransaction`boolean | Whether or not to proceed with the transaction. |
| `addressVerification`object | Details about the cardholder's address. These help in the validation and fraud prevention process by matching the provided address with the cardholder's address on file. |
| `addressVerification.countryCode`string (≤ 2 characters) | The country associated with the cardholder's address, in ISO 3166-1 alpha-2 format. |
| `addressVerification.houseNumberOrName`string (≤ 100 characters) | The house number or name associated with the cardholder's address. |
| `addressVerification.postalCode`string (≤ 10 characters) | The postal code of the cardholder's address. |
| `identityVerification`object | Details about the cardholder's identity. These help in ensuring that the information provided matches the cardholder's details on file. |
| `identityVerification.nameVerification`boolean | Whether the cardholder's name matches the name associated with the registered address on file. |
| `threeDSecureData`object | Details about the 3D Secure authentication data from an external authentication process. |
| `threeDSecureData.threeDSecureVersion`string (≤ 10 characters) | The 3DS protocol version. |
| `threeDSecureData.electronicCommerceIndicator`string (≤ 2 characters) | The ECI value indicating the authentication result. |
| `threeDSecureData.cardHolderAuthenticationVerificationValue`string (≤ 50 characters) | The CAVV value from 3DS authentication. |
| `threeDSecureData.directoryServerTransactionId`string (≤ 50 characters) | The Directory Server transaction identifier. |
| `threeDSecureData.threeDSecureTransactionStatus`string (≤ 1 character) | The 3DS transaction status. |


### Prepare your request

Put these four parts together following this format: `"{timestamp}{requestId}{requestPath}{requestBody}"`. The result should look something like this:


```json
1754701373ce244054-b372-42c2-9102-f0d976db69f6api/v1/sessions{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "card": "Authorisation",
      "paypal": "Purchase"
    }
  },
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  },
  "allowTransaction": true,
  "addressVerification": {
    "countryCode": "GB",
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "threeDSecureData": {
    "threeDSecureVersion": "2.2",
    "electronicCommerceIndicator": "05",
    "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
    "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDSecureTransactionStatus": "Y"
  }
}
```

Use your token ID to encrypt this data structure by SHA256. You can find your token ID in the Unity Portal. Here's an example of an `hmacSignature` after you've encrypted the data:


```json
1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6
```

You can now put together your `Authorization` header. It follows this format: `PXP-UST1 {tokenId}:{timestamp}:{hmacSignature}`. For example:


```
"PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6"
```

### Send your request

Lastly, send your request to the Sessions API. You'll need to add a request ID of your choice and include your client ID, which you can find in the Unity Portal.

Here's a full example of what your request might look like:


```curl
curl -i -X POST \
  'https://api-services.pxp.io/api/v1/sessions' \
  -H 'Authorization: "PXP-UST1 9aac6071-38d0-4545-9d2f-15b936af6d7f:1754701373:1DE2DFC390D7CD746A972140F26846AFA81CF85F5A0BAABA95DBC95301795EA6"' \
  -H 'X-Request-Id: "550e8400-e29b-41d4-a716-446655440000"' \
  -H 'X-Client-Id: "f47ac10b-58cc-4372-a567-0e02b2c3d479"' \
  -H 'Content-Type: application/json' \
  -d '{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "sessionTimeout": 120,
  "merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
  "transactionMethod": {
    "intent": {
      "card": "Authorisation",
      "paypal": "Purchase"
    }
  },
  "amounts": {
    "currencyCode": "EUR",
    "transactionValue": 20
  },
  "allowTransaction": true,
  "addressVerification": {
    "countryCode": "GB",
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "threeDSecureData": {
    "threeDSecureVersion": "2.2",
    "electronicCommerceIndicator": "05",
    "cardHolderAuthenticationVerificationValue": "CAVV1234567890",
    "directoryServerTransactionId": "550e8400-e29b-41d4-a716-446655440000",
    "threeDSecureTransactionStatus": "Y"
  }
}'
```

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


```json
{
  "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": {
        "merchantId": "merchant.com.example.pay"
      },
      "googlePay": {
        "merchantId": "BCR2DN4T7654321",
        "merchantName": "Example Merchant"
      }
    }
  }
}
```

| 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`object or null | The supported wallet payment methods. |
| `allowedFundingTypes.wallets.paypal`object | PayPal wallet configuration. |
| `allowedFundingTypes.wallets.paypal.allowedFundingOptions`array of strings | The list of allowed PayPal funding options (e.g., `venmo`, `paylater`, `paypal`). |
| `allowedFundingTypes.wallets.applePay`object | Apple Pay wallet configuration. |
| `allowedFundingTypes.wallets.applePay.merchantId`string | Your Apple Pay merchant identifier. |
| `allowedFundingTypes.wallets.googlePay`object | Google Pay wallet configuration. |
| `allowedFundingTypes.wallets.googlePay.merchantId`string | Your Google Pay merchant identifier. |
| `allowedFundingTypes.wallets.googlePay.merchantName`string | Your merchant name displayed in the Google Pay payment sheet. |


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

This example shows the `new-card` component, which is a pre-built component that works with minimal configuration. Other components may require different setup steps and configuration options. See the [implementation guide](/guides/components/web/card/implementation) for comprehensive details on all available components.


```typescript
import { PxpCheckout } from "@pxpio/web-components-sdk";
import { useEffect, useState } from "react";

export default function CreateComponent() {
  const [pxpCheckout, setPxpCheckout] = useState<PxpCheckout>();
  const [newCardComponent, setNewCardComponent] = useState<any>();

  useEffect(() => {
    initialiseTheSdkAsync();
  }, []);

  useEffect(() => {
    if (!pxpCheckout) return;
    // Create and customise components
    setNewCardComponent(pxpCheckout.create("new-card"));
  }, [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",
      // kountDisabled: false, // Optional: Set to true to disable Kount fraud detection
      transactionData: {
        currency: "USD",
        amount: 25,
        entryType: "Ecom",
        intent: {
          card: "Authorisation",
          paypal: "Purchase"
        },
        merchantTransactionId: crypto.randomUUID(),
        merchantTransactionDate: () => new Date().toISOString(),
      },
      onGetShopper: () => {
        // Return current shopper data dynamically
        return Promise.resolve({
          id: 'shopper-123',
          email: 'customer@example.com',
          firstName: 'John',
          lastName: 'Doe',
          phoneNumber: '+1-555-0123'
        });
      },
      onGetShippingAddress: () => {
        // Return current shipping address dynamically
        return Promise.resolve({
          address: '123 Main Street',
          addressLine2: 'Apt 4B',
          city: 'New York',
          state: 'NY',
          postalCode: '10001',
          countryCode: 'US'
        });
      }
    });

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

| Parameter | Description |
|  --- | --- |
| `environment`string | The environment type.Possible values:`test``live` |
| `session`sessionData | Details about the checkout session. |
| `ownerId`string | The identifier of the owner related to the `ownerType`. |
| `ownerType`string | The type of owner. Set this to `MerchantGroup`. Possible values:`MerchantGroup``Merchant` `Site`   |
| `kountDisabled`boolean | Whether to disable the Kount fraud detection service. Defaults to `false` (Kount is enabled). Set to `true` to disable Kount for this session. |
| `onGetShopper`function | Callback function to provide shopper data dynamically. Returns a Promise with shopper information including ID, email, name, and contact details. |
| `onGetShippingAddress`function | Callback function to provide shipping address data dynamically. Returns a Promise with current shipping address information. |
| `transactionData`object | Details about the transaction. |
| `transactionData.currency`string (1-3 characters) | The currency code associated with the transaction, in ISO 4217 format. |
| `transactionData.amount`number | The transaction amount. |
| `transactionData.entryType`string | The entry type.Possible values: `Ecom``Moto` |
| `transactionData.intent`object | The transaction intents for each payment method. Learn more about intents for [card](/guides/components/web/card/how-it-works#supported-transaction-intents), [PayPal](/guides/components/web/paypal/how-it-works#supported-transaction-intents), [Apple Pay](/guides/components/web/applepay/how-it-works#supported-transaction-intents), or [Google Pay](/guides/components/web/google-pay/how-it-works#payment-flows). |
| `transactionData.intent.card`string | The intent for card, Apple Pay, or Google Pay transactions.Possible values:`Authorisation``EstimatedAuthorisation``Purchase``Payout``Verification` |
| `transactionData.intent.paypal`string | The intent for PayPal transactions.Possible values:`Authorisation``Purchase``Payout` |
| `transactionData.merchantTransactionId`string | A unique identifier for this transaction. |
| `transactionData.merchantTransactionDate`function | A function that returns the date and time of the transaction as a string in ISO 8601 format. |
| `analyticsEvent`function | Callback function for receiving analytics events. Receives a `BaseAnalyticsEvent` object. |


That's it! You've got your first card component up and running.

## What's next?

Now that you've installed the SDK and created your first component, choose the payment method you want to implement and follow the relevant guide:

- [Card](/guides/components/web/card/how-it-works)
- [PayPal](/guides/components/web/paypal/how-it-works)
- [Apple Pay](/guides/components/web/applepay/how-it-works)
- [Google Pay](/guides/components/web/google-pay/how-it-works)
- [PayPal/Venmo payouts](/guides/components/web/paypal/payouts/how-it-works)