# Quickstart

Follow our walkthrough to get Components for Web running in minutes.

This quickstart focuses on card payments in the test environment. Components for Web also supports Apple Pay, Google Pay, PayPal, Paze, and Aeropay. See [What's next?](#whats-next) for the available payment-method guides.

## Pre-requisites

Before you start, make sure you have:

ul
li
Node.js 22.x or higher installed on your computer
li
Your API credentials from the 
a
Unity Portal
Where to find your credentials
1. In the Unity Portal, go to **Merchant setup > Merchant groups** and select a merchant group.
2. Click the **Inbound calls** tab. Your client ID is in the top right.
3. Click **+ New token** to create a token, then copy both the **ID** and the **Value**.


## Install the SDK

Install the version of the Web SDK tested with this quickstart from the npm public registry. You'll need Node.js 22.x or higher.

```shell
npm i @pxpio/web-components-sdk
```

## Create a session on your backend

Components for Web needs a session from the PXP API. This must happen on your backend using Hash-based Message Authentication Code (HMAC) authentication.

Set your token ID, token value, and client ID as the `PXP_TOKEN_ID`, `PXP_TOKEN_VALUE`, and `PXP_CLIENT_ID` environment variables. Never hardcode them in your application.

This function generates a secure authentication hash by combining timestamp, request ID, request path, and request body, then hashing with your token value using HMAC SHA256.

Load the order by its ID on your backend, then create a request with the server-controlled merchant, site, amount, and currency. The request body must be minified (no whitespace) for the HMAC signature.

Call the signature function with your credentials and request details.

POST to `https://api-services.dev.pxp.io/api/v1/sessions` with your authentication headers and request body.

The API returns `sessionId`, `hmacKey`, `encryptionKey`, and `allowedFundingTypes`. Return a payload that matches what your frontend expects: the session object plus the server-controlled `merchantTransactionId`, amount, and currency.

Call the Modify session API to set `authentication = false`. This creates a non-3D Secure (3DS) flow. See [3D Secure](/guides/checkout/components/web/card/3ds) before enabling authentication.

Register `/api/sessions` on your existing backend. Require an order ID and idempotency key, then load the authoritative order before creating or reusing a session.

## Initialise the card component on your frontend

Import `PxpCheckout` and necessary types from the Web SDK.

Create a React component that hosts the card payment interface. Pass the authenticated order ID and merchant group ID from your application.

Call your backend endpoint to get the session data you created in the previous steps.

Configure the SDK with your environment, session data, owner details, and transaction information.

Specify the currency, amount, entry type, and payment intent for card transactions.

Implement `onGetShopper` to get shopper details for the authenticated customer from your backend. The SDK calls this callback whenever it needs shopper data during the payment flow.

The shopper `id` enables card-on-file (COF) and one-click payments. It also identifies the shopper when they consent to storing a card. Use a stable, unique ID from your authenticated backend. Don't use a shared or browser-supplied value.

If you don't provide a shopper ID:

* Card-on-file components can't retrieve saved cards.
* One-click payment functionality doesn't work.
* The consent tickbox can't store a card against a shopper.


If you provide a shopper ID:

* Card-on-file and one-click components retrieve cards from the Token Vault for that shopper.
* When the shopper selects the configured consent checkbox, their card is stored under that shopper ID for future use.


Use the SDK's `create()` method to create a new card component with your desired configuration.

Set up the card number, expiry date, Card Verification Code (CVC), cardholder name, and card-consent fields.

Customise the submit button text and styling to match your brand.

Implement `onPostAuthorisation` to handle the PXP response. The callback can receive either `MerchantSubmitResult` or `FailedSubmitResult`. Always verify successful payments on your backend before fulfilling orders because frontend callbacks can be manipulated.

Implement `onSubmitError` to handle SDK, network, or unexpected submission errors. Failed PXP transaction responses are returned to `onPostAuthorisation` as `FailedSubmitResult`.

Implement the asynchronous `onPreAuthorisation` callback. Return an empty object `{}` to proceed, or include Address Verification Service (AVS) or risk-screening data.

Call the `mount()` method with your container element ID to render the payment form.

Return JSX that includes a container div where the card component will mount itself.

## Verify payments

When PXP returns an authorisation response, `onPostAuthorisation` receives a success or failure result. For `MerchantSubmitResult`, always verify the payment on your backend before fulfilling orders.

Configure webhooks in the Unity Portal to receive real-time payment notifications on your backend.

Register `/webhooks/pxp` to receive payment notifications from Unity. Verify the webhook signature against the raw request body before processing any event. Pass your Express-compatible application, signature verifier, and persistence functions to `registerPxpWebhook()`.

Loop through the events array and filter for Transaction events.

Verify the transaction state is `Authorised` or `Captured` before processing.

Skip events you've already handled by checking `systemTransactionId` before fulfilment.

Match the `merchantTransactionId`, amount, and currency against your order records.

If verification passes, fulfil the order and mark the transaction as processed.

After authenticating the request, return `{ state: 'Success' }` to acknowledge receipt. Handle fulfilment failures through your own retry and incident process rather than failing the webhook response in this sample.

Register `/api/verify-payment` on your backend. Load the authenticated customer's order and retrieve the authoritative transaction from PXP before returning a verified result.

You can also verify payments using the Transactions API to query transaction status directly. See [Backend verification](/guides/checkout/components/web/card/implementation#step-8-backend-verification-critical) for details.

You now have the core fragments needed to add a card payment integration to your application.

## What's next?

Now that you have card components running, here are the recommended next steps:

**Explore other payment methods:**

ul
li
a
Apple Pay
li
a
Google Pay
li
a
PayPal
li
a
Paze
li
a
Aeropay
**Enhance your card integration:**

ul
li
a
Customise the look and feel
to match your brand
li
a
Explore additional components
like billing address, 
a
card-on-file
, and 
a
one-click payments
li
a
Add event callbacks
to enhance the user experience with validation and loading states
li
a
Enable 3D Secure
for enhanced security and liability shift