Skip to content

Implementation

Complete guide to integrating Payout Drop-in into your application.

Overview

Payout Drop-in provides a pre-built withdrawal interface for stored payout instruments. It follows a simple lifecycle:

  1. Initialise: Call PayoutDropIn.initialize() with the environment, payout session, transaction data, and callbacks.
  2. Mount: Call create(containerId) to load site configuration, resolve instruments, and render payout methods.
  3. 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.

Before you start

Complete these prerequisites:

  1. Activate Payout Drop-in for the site in the Unity Portal. See Activation.
  2. Configure the allowed payout methods and branding for the site. See Payout methods and Branding.
  3. Ensure test shoppers have eligible stored instruments (or plan to test empty-state and error paths). See Onboarding.
  4. Get the inbound API credentials (client ID and token) required for session creation. See Authentication.

Step 1: Install the Web SDK library

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-sdk
import {
  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.

Step 2: Get your API credentials

Session creation uses HMAC authentication. Keep credentials on your backend only.

To get your credentials:

  1. In the Unity Portal, go to Merchant setup > Merchant groups.
  2. Select the merchant group that owns the site.
  3. Open 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. 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.

Step 3: Create a payout session on your backend

Payout Drop-in requires a session from the Sessions API. Create it on your backend with HMAC authentication so inbound credentials stay secure.

Understanding HMAC authentication

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.

Session request parameters

Use these fields when you create the session:

ParameterDescription
merchant
string (≤ 20 characters)
required
Your merchant identifier from the Unity Portal (Merchant setup > Merchants).
site
string (≤ 100 characters)
required
Your site identifier from the Unity Portal (Merchant setup > Sites).
merchantTransactionId
string (≤ 50 characters)
required
A unique ID for this withdrawal attempt.
sessionTimeout
number
The session lifetime in minutes (≥ 1).
amounts.currencyCode
string (3 characters)
required
The ISO 4217 currency code.
amounts.transactionValue
number
required
The withdrawal amount.
transactionMethod.intent
object
required
At least one intent property. For Payout Drop-in, use Payout on each method you enable (e.g., card and paypal).
allowTransaction
boolean
Whether the session may proceed with transactions.
serviceType
string
required
Must be "PayoutDropIn".
customerProfileId
string (≤ 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"
}

Prepare and send your request

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.

Session response

On success you receive HTTP 200 with session properties such as:

PropertyUse
sessionIdThe SDK session identity.
hmacKeyThe session-scoped Unity API authentication key (not your inbound API token).
encryptionKeyThe encryption key for sensitive SDK payloads.
sessionExpiryThe session lifetime.
allowedFundingTypesWhich payout methods the SDK may consider.
restrictionsSession restrictions when returned.
isClosedLoopEnforcedWhen 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.

Step 4: Initialise Payout Drop-in on your frontend

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);
  },
});

Configuration parameters

Use these required properties when you initialise Drop-in:

ParameterDescription
environment
string
required
The environment value: test for development and testing, or live for production.
session
SessionData
required
The session object from your backend, including sessionId, hmacKey, and usually allowedFundingTypes.
ownerId
string
required
The merchant group ID used for token vault lookups.
transactionData
object
required
The amount, currency, entry type, and merchant transaction identifiers. Match the session amounts and ID.
transactionData.currency
string
required
The ISO 4217 currency code. Match the session currency.
transactionData.amount
number
required
The payout amount. Match the session amount.
transactionData.entryType
string
required
The channel: Ecom or Moto.
transactionData.merchantTransactionId
string
required
The same ID used when creating the session.
transactionData.merchantTransactionDate
function
required
A function that returns an ISO 8601 timestamp string.
onGetShopper
function
A strongly recommended callback that returns Promise<{ id: string }> for vault and PayPal lookups.
onBeforeSubmit
function
A callback for card, Apple Pay, and Google Pay only. Return false to cancel.
onSubmit
function
A callback for card, Apple Pay, and Google Pay only. Fires when card-on-file submit starts.
onSuccess
function
required
The callback fires after successful SDK payout submission.
onError
function
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.

Step 5: Mount Drop-in to your page

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 SDK1700 or SDK1701 through onError when configuration fails or no methods remain. In those cases create() 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.

Step 6: Handle callbacks

onGetShopper

Return the authenticated shopper ID used for vault and PayPal lookups:

onGetShopper: async () => {
  const user = await getAuthenticatedUser();
  return { id: user.shopperId };
},

onSuccess

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

onError

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.

Integration architecture

A typical Web integration follows this sequence:

  1. The shopper opens your payout page.
  2. Your frontend requests payout context from your backend.
  3. Your backend creates a payout session with HMAC authentication and returns session data plus matching transaction details.
  4. Your frontend calls PayoutDropIn.initialize() and then create(containerId).
  5. The SDK loads payout Drop-in configuration, active tokens, and wallet associations as needed, then renders eligible methods.
  6. The shopper submits a payout. The SDK calls PXP payout APIs and delivers onSuccess or onError.
  7. Your frontend asks your backend to reconcile payout status before updating the withdrawal.

Method availability logic

Drop-in builds a candidate list from allowedFundingTypes:

  • Card: When allowedFundingTypes.cards is present (including []). cardSchemes alone isn't enough.
  • Apple Pay and Google Pay: When the corresponding wallets.applePay or wallets.googlePay entry exists.
  • PayPal: When wallets.paypal is allowed and an active linked PayPal account is returned for the shopper.

Then Drop-in:

  1. Applies merchant methodConfig blacklists.
  2. Builds card-on-file bundles and drops card, Apple Pay, or Google Pay when no visible tokens remain.
  3. Orders methods using site branding configuration (manualOrder when set; otherwise the SDK default order).
  4. If no methods remain after mount filtering, reports SDK1701 through onError.

Card-on-file payout flow

This flow applies to card, Apple Pay, and Google Pay.

Card-on-file submit runs in this order:

  1. The shopper selects a stored token and confirms withdrawal.
  2. Optional onBeforeSubmit runs. Return false to cancel.
  3. onSubmit fires when card-on-file submit starts.
  4. The payout initiation completes with onSuccess or onError.

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.

Backend verification

Before marking a withdrawal complete:

  1. Confirm the transaction exists. Query by systemTransactionId, or each ID in payouts for closed-loop.
  2. Match the amount and currency to the authorised withdrawal.
  3. Match merchantTransactionId to your internal withdrawal record.
  4. Deduplicate webhook or callback delivery using systemTransactionId.

See Quickstart for an end-to-end pattern and Testing for a pre-production checklist.

Merchant responsibilities

Backend

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.

Frontend

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.

What's next?

Continue with these guides: