# Quickstart

Follow our walkthrough to get Checkout Drop-in running in minutes.

## Pre-requisites

Before you start, make sure you have:

ul
li
Node.js 22.x or higher (for Node.js backend) or .NET SDK (for .NET backend) 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

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
```

## Create a session on your backend

Drop-in needs a session from the PXP API. This must happen on your backend using HMAC authentication.

Set up your API credentials as environment variables — never hardcode them in your application.

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

Create a request with your merchant details and transaction information. The request body must be minified (no whitespace) for the HMAC signature.

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

The API returns `sessionId`, `hmacKey`, `encryptionKey`, and `allowedFundingTypes`. Pass this entire response to your frontend.

## Initialise Drop-in on your frontend

Import `CheckoutDropIn`, `IntentType`, and the other symbols you need from the Web SDK package root (`@pxpio/web-components-sdk`). Prefer a single named import over paths under `/src/`.

Create a React component that will host the Checkout Drop-in interface.

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

Configure Drop-in with your environment, session data, and transaction details.

Specify the currency, amount, entry type, and payment intents for each payment method.

Implement the `onGetShopper` callback to provide shopper information. This is required for Card-on-File functionality.

Implement the `onSuccess` callback to handle successful payments. Always verify payments on your backend before fulfilling orders — frontend callbacks can be manipulated.

Implement the `onError` callback to handle payment failures and display appropriate error messages.

Call the `create()` method with your container element ID to render the payment interface.

Return JSX that includes a container div where Checkout Drop-in will mount itself.

## Verify payments

When a payment succeeds, the `onSuccess` callback fires with transaction details. However, you must **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.

Set up an endpoint at `/webhooks/pxp` to receive payment notifications from Unity.

Loop through the events array and filter for Transaction events.

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

Check if you've already processed this transaction using `systemTransactionId`.

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

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

Always return `{ state: 'Success' }` to acknowledge receipt, even if processing failed.

You can also verify payments using the Transactions API to query transaction status directly. See the [Integration guide](/guides/checkout/drop-in/web/implementation#backend-verification-critical) for details.

That's it! You now have a working Checkout Drop-in integration.

## What's next?

Now that you have Drop-in running, here are the recommended next steps:

ul
li
strong
a
Customise the look and feel
to match your brand
li
strong
a
Set up backend verification for Web
to verify payments before fulfilling orders
li
strong
a
Add optional callbacks for Web
to enhance the user experience with validation and loading states
li
strong
a
Enable Aeropay
for USD pay-by-bank payments when Aeropay is enabled in your session