Complete guide to integrating Payout Drop-in into your application.
Payout Drop-in provides a pre-built withdrawal interface for stored payout instruments. It follows a simple lifecycle:
- Initialise: Call
PayoutDropIn.initialize()with the environment, payout session, transaction data, and callbacks. - Mount: Call
create(containerId)to load site configuration, resolve instruments, and render payout methods. - Handle callbacks: Use
onSuccess,onError, and optional hooks to drive your UX and backend reconciliation.
Drop-in shows methods only when the session allows them and the shopper has an eligible stored instrument after filtering (expiry, wallet type, blacklist, and so on).
Backend verification is mandatory. Always reconcile payout status on your merchant backend before completing a withdrawal. Frontend callbacks can be manipulated and aren't proof of settlement.
Complete these prerequisites:
- Activate Payout Drop-in for the site in the Unity Portal. See Activation.
- Configure the allowed payout methods and branding for the site. See Payout methods and Branding.
- Ensure test shoppers have eligible stored instruments (or plan to test empty-state and error paths). See Onboarding.
- Get the inbound API credentials (client ID and token) required for session creation. See Authentication.
Install the latest version of the Web SDK from the npm public registry. You'll need Node.js 22.x or higher for the frontend package installation.
npm i @pxpio/web-components-sdkimport {
PayoutDropIn,
type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';Import from the package root and avoid deep /src/ paths in merchant applications, unless your build pipeline requires them.
Session creation uses HMAC authentication. Keep credentials on your backend only.
To get your credentials:
- In the Unity Portal, go to Merchant setup > Merchant groups.
- Select the merchant group that owns the site.
- Open 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. Copy the token ID and token value.
Rotate tokens on a regular schedule. Store values in server-side secrets only. Never ship token values to the browser.
Payout Drop-in requires a session from the Sessions API. Create it on your backend with HMAC authentication so inbound credentials stay secure.
The platform uses HMAC-SHA256. Concatenate these values in order, with no separators:
- Timestamp: The current time in Unix seconds (UTC)
- Request ID: A unique GUID for this request
- Request path:
api/v1/sessions(no leading slash) - Request body: The complete JSON request body as a minified string
{timestamp}{requestId}{requestPath}{requestBody}Create an HMAC SHA256 hash of that string using your token value as the secret key. Encode the digest as uppercase hex.
When creating the HMAC signature, the request body must be minified (no whitespace or formatting). Formatted JSON in these docs is for readability only.
Use these fields when you create the session:
| Parameter | Description |
|---|---|
merchantstring (≤ 20 characters) required | Your merchant identifier from the Unity Portal (Merchant setup > Merchants). |
sitestring (≤ 100 characters) required | Your site identifier from the Unity Portal (Merchant setup > Sites). |
merchantTransactionIdstring (≤ 50 characters) required | A unique ID for this withdrawal attempt. |
sessionTimeoutnumber | The session lifetime in minutes (≥ 1). |
amounts.currencyCodestring (3 characters) required | The ISO 4217 currency code. |
amounts.transactionValuenumber required | The withdrawal amount. |
transactionMethod.intentobject required | At least one intent property. For Payout Drop-in, use Payout on each method you enable (e.g., card and paypal). |
allowTransactionboolean | Whether the session may proceed with transactions. |
serviceTypestring required | Must be "PayoutDropIn". |
customerProfileIdstring (≤ 255 characters) | A customer profile ID. When present, the session service can apply customer profile method allow lists and limits from Payout Drop-in configuration. |
The following example body is formatted for reading. Minify it before you sign the request:
{
"merchant": "MERCHANT-1",
"site": "SITE-1",
"sessionTimeout": 120,
"merchantTransactionId": "0ce72cfd-014d-4256-a006-a56601b2ffc4",
"amounts": {
"currencyCode": "USD",
"transactionValue": 25.0
},
"transactionMethod": {
"intent": {
"card": "Payout",
"paypal": "Payout"
}
},
"allowTransaction": true,
"serviceType": "PayoutDropIn"
}Your Authorization header follows this format:
PXP-UST1 {tokenId}:{timestamp}:{signature}Example curl (the JSON body string must match the payload you signed exactly):
curl -i -X POST \
'https://api-services.pxp.io/api/v1/sessions' \
-H 'Authorization: PXP-UST1 {tokenId}:{timestamp}:{signature}' \
-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":"0ce72cfd-014d-4256-a006-a56601b2ffc4","amounts":{"currencyCode":"USD","transactionValue":25},"transactionMethod":{"intent":{"card":"Payout","paypal":"Payout"}},"allowTransaction":true,"serviceType":"PayoutDropIn"}'Validate the shopper and withdrawal on your server before calling the Sessions API. Return session data only to that authenticated shopper.
On success you receive HTTP 200 with session properties such as:
| Property | Use |
|---|---|
sessionId | The SDK session identity. |
hmacKey | The session-scoped Unity API authentication key (not your inbound API token). |
encryptionKey | The encryption key for sensitive SDK payloads. |
sessionExpiry | The session lifetime. |
allowedFundingTypes | Which payout methods the SDK may consider. |
restrictions | Session restrictions when returned. |
isClosedLoopEnforced | When true, Drop-in can enter closed-loop enforcement UI where configured. |
Example shape (values vary by site):
{
"sessionId": "c5f0799b-0839-43ce-abc5-5b462a98f250",
"hmacKey": "904bc42395d4af634e2fd48ee8c2c7f52955a1da97a3aa3d82957ff12980a7bb",
"encryptionKey": "20d175a669ad3f8c195c9c283fc86155",
"sessionExpiry": "2025-05-19T13:39:20.3843454Z",
"allowedFundingTypes": {
"cardSchemes": ["Visa", "Mastercard"],
"cards": [],
"wallets": {
"paypal": {},
"applePay": {},
"googlePay": {}
}
}
}allowedFundingTypes gates candidate methods only. Card requires the cards field to be present (including an empty array). cardSchemes alone doesn't enable it. Wallet objects may also include provider metadata such as merchantId when those methods are enabled for the site. Eligible stored instruments and PayPal wallet state still determine what the shopper sees.
Return the Sessions API JSON as session, plus transactionData with the same merchantTransactionId, amount, and currency used to create the session.
Pass the session and matching transaction data into PayoutDropIn.initialize():
import {
PayoutDropIn,
type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';
const { session, transactionData } = await fetch('/api/create-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
amount: 25,
currency: 'USD',
}),
}).then((response) => response.json());
const payoutDropIn = PayoutDropIn.initialize({
environment: 'test',
session,
ownerId: 'YOUR-MERCHANT-GROUP-ID',
transactionData: {
currency: transactionData.currency,
amount: transactionData.amount,
entryType: 'Ecom',
merchantTransactionId: transactionData.merchantTransactionId,
merchantTransactionDate: () => new Date().toISOString(),
},
onGetShopper: async () => ({ id: 'authenticated-shopper-id' }),
onBeforeSubmit: async (payoutMethod) => {
console.log('About to submit:', payoutMethod);
return true;
},
onSubmit: (payoutMethod) => {
console.log('Submit started:', payoutMethod);
},
onSuccess: async (result: PayoutDropInSubmitResult) => {
await verifyPayoutOnBackend(result);
},
onError: (error: BaseSdkException) => {
console.error(error.ErrorCode, error.message);
},
});Use these required properties when you initialise Drop-in:
| Parameter | Description |
|---|---|
environmentstring required | The environment value: test for development and testing, or live for production. |
sessionSessionData required | The session object from your backend, including sessionId, hmacKey, and usually allowedFundingTypes. |
ownerIdstring required | The merchant group ID used for token vault lookups. |
transactionDataobject required | The amount, currency, entry type, and merchant transaction identifiers. Match the session amounts and ID. |
transactionData.currencystring required | The ISO 4217 currency code. Match the session currency. |
transactionData.amountnumber required | The payout amount. Match the session amount. |
transactionData.entryTypestring required | The channel: Ecom or Moto. |
transactionData.merchantTransactionIdstring required | The same ID used when creating the session. |
transactionData.merchantTransactionDatefunction required | A function that returns an ISO 8601 timestamp string. |
onGetShopperfunction | A strongly recommended callback that returns Promise<{ id: string }> for vault and PayPal lookups. |
onBeforeSubmitfunction | A callback for card, Apple Pay, and Google Pay only. Return false to cancel. |
onSubmitfunction | A callback for card, Apple Pay, and Google Pay only. Fires when card-on-file submit starts. |
onSuccessfunction required | The callback fires after successful SDK payout submission. |
onErrorfunction required | The callback fires for configuration, empty-method, and payout failures on the SDK error path. |
ownerType is set to MerchantGroup inside PayoutDropIn.initialize(), so you don't need to pass it. Don't pass payment intents on frontend transactionData: the SDK sets payout intents internally. Session intents are fixed when you create the session with Payout.
See Configuration for methodConfig, localisation, closed-loop options, and the full reference.
Add a container element:
<div id="payout-drop-in-container"></div>Then mount:
try {
await payoutDropIn.create('payout-drop-in-container');
} catch (error) {
console.error('Mount failed:', error);
}During create(), Drop-in:
- Shows a loading shell in the container.
- Calls
onGetShopper(if provided). - Loads payout Drop-in site configuration.
- Resolves stored card or wallet tokens and PayPal association where applicable.
- Renders available methods in an accordion, ordered from the site configuration. For the methods covered in these guides, the relative default order is card, Apple Pay, Google Pay, then PayPal. Other enabled methods can appear in the default list between or after those entries.
- Reports
SDK1700orSDK1701throughonErrorwhen configuration fails or no methods remain. In those casescreate()usually settles without throwing.
Call destroy() when the page or route unmounts to clear components and container shell markup.
Catch synchronous throws from initialize() (missing session fields) and promise rejections from create() (e.g., a rejected onGetShopper). Those paths don't always call onError.
Return the authenticated shopper ID used for vault and PayPal lookups:
onGetShopper: async () => {
const user = await getAuthenticatedUser();
return { id: user.shopperId };
},Treat this as submission acknowledgement only. Verify on your backend before updating withdrawal status:
onSuccess: async (result: PayoutDropInSubmitResult) => {
const verified = await fetch('/api/verify-payout', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
systemTransactionId: result.systemTransactionId,
merchantTransactionId: result.merchantTransactionId,
payoutMethod: result.payoutMethod,
payouts: result.payouts,
}),
}).then((response) => response.json());
if (verified.success) {
window.location.href = `/withdrawals/${verified.id}/status`;
}
},Map ErrorCode to shopper-safe messages. See Error handling.
onError: (error: BaseSdkException) => {
console.error(error.ErrorCode, error.message, error.details);
showErrorMessage(mapToCustomerSafeMessage(error));
},Full callback behaviour and ordering are documented in Events.
A typical Web integration follows this sequence:
- The shopper opens your payout page.
- Your frontend requests payout context from your backend.
- Your backend creates a payout session with HMAC authentication and returns session data plus matching transaction details.
- Your frontend calls
PayoutDropIn.initialize()and thencreate(containerId). - The SDK loads payout Drop-in configuration, active tokens, and wallet associations as needed, then renders eligible methods.
- The shopper submits a payout. The SDK calls PXP payout APIs and delivers
onSuccessoronError. - Your frontend asks your backend to reconcile payout status before updating the withdrawal.
Drop-in builds a candidate list from allowedFundingTypes:
- Card: When
allowedFundingTypes.cardsis present (including[]).cardSchemesalone isn't enough. - Apple Pay and Google Pay: When the corresponding
wallets.applePayorwallets.googlePayentry exists. - PayPal: When
wallets.paypalis allowed and an active linked PayPal account is returned for the shopper.
Then Drop-in:
- Applies merchant
methodConfigblacklists. - Builds card-on-file bundles and drops card, Apple Pay, or Google Pay when no visible tokens remain.
- Orders methods using site branding configuration (
manualOrderwhen set; otherwise the SDK default order). - If no methods remain after mount filtering, reports
SDK1701throughonError.
This flow applies to card, Apple Pay, and Google Pay.
Card-on-file submit runs in this order:
- The shopper selects a stored token and confirms withdrawal.
- Optional
onBeforeSubmitruns. Returnfalseto cancel. onSubmitfires when card-on-file submit starts.- The payout initiation completes with
onSuccessoronError.
PayPal uses onSuccess and onError only. The card-on-file UI can allow delete token and edit expiry where enabled; CVC isn't required on this payout submit path.
Before marking a withdrawal complete:
- Confirm the transaction exists. Query by
systemTransactionId, or each ID inpayoutsfor closed-loop. - Match the amount and currency to the authorised withdrawal.
- Match
merchantTransactionIdto your internal withdrawal record. - Deduplicate webhook or callback delivery using
systemTransactionId.
See Quickstart for an end-to-end pattern and Testing for a pre-production checklist.
On the backend:
- Authenticate shoppers and authorise withdrawals.
- Create payout sessions with validated amounts and profiles.
- Keep inbound API tokens secret.
- Reconcile payout state via webhooks or the Transactions API.
On the frontend:
- Fetch session data from your backend only.
- Pass an authenticated shopper ID via
onGetShopper. - Handle callbacks and call backend verification endpoints.
- Destroy Drop-in instances on navigation unmount.
Continue with these guides:
- Configuration: Review the full initialiser reference.
- Events: Handle callback details and ordering.
- Error handling: Recover from SDK error codes.
- Troubleshooting: Diagnose common symptoms.