Skip to content

Analytics

Get actionable, trackable data instantly to drive better decisions and performance.

Overview

Analytics events are structured data objects that the SDK raises when significant actions or states occur in Payout Drop-in. Use them to monitor the withdrawal journey in your own analytics or CRM tools.

Analytics events allow you to:

  • Observe Drop-in lifecycle and interaction events in your own tooling.
  • Optimise conversion rates and reduce drop-offs with actionable insights.
  • Feed real-time data into your analytics and CRM systems.

analyticsEvent is optional. Treat it as observational alongside onSuccess, onError, and your backend webhook handling for payout outcomes. Don't block the withdrawal UI waiting for analytics network calls.

Consume an event

Pass an analyticsEvent callback to PayoutDropIn.initialize. The SDK calls it with each event object. Use event.eventName to route payloads.

For example:

import {
  PayoutDropIn,
  type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';

const payoutDropIn = PayoutDropIn.initialize({
  environment: 'test',
  session: sessionData,
  ownerId: 'MERCHANT-1',
  transactionData: {
    currency: 'USD',
    amount: 25,
    entryType: 'Ecom',
    merchantTransactionId: 'withdrawal-123',
    merchantTransactionDate: () => new Date().toISOString(),
  },
  onGetShopper: () => Promise.resolve({ id: 'shopper-001' }),
  analyticsEvent: (event) => {
    console.log('Analytics event:', event.eventName, event);

    if (typeof gtag !== 'undefined') {
      gtag('event', event.eventName, {
        session_id: event.sessionId,
        timestamp:
          event.timestamp instanceof Date
            ? event.timestamp.toISOString()
            : event.timestamp,
      });
    }
  },
  onSuccess: async (result: PayoutDropInSubmitResult) => {
    await verifyPayoutOnBackend(result);
  },
  onError: (error: BaseSdkException) => {
    console.error('Payout failed:', error);
  },
});

await payoutDropIn.create('payout-drop-in-container');

Every event includes at least:

  • eventName: The event identifier (e.g., DeviceType).
  • sessionId: The payout session identifier.
  • timestamp: The date and time when the event was created.

Supported events

The tables below list events the Web SDK can raise during a Payout Drop-in session. Exact events depend on which methods and user interface steps the shopper uses.

Initialisation

Raised once when you call PayoutDropIn.initialize.

Event nameStructure
DeviceType
  • eventName
  • timestamp
  • deviceType
  • pageUrl
  • sessionId
BrowserData
  • eventName
  • timestamp
  • browserType
  • browserVersion
  • operatingSystem
  • pageUrl
  • sessionId

Drop-in and panel lifecycle

Raised when Drop-in panels and nested components mount or unmount, and when component-level errors occur (including some SDK and Unity service failures surfaced through the shared analytics callback).

Event nameStructure
ComponentLifecycleEvent
  • eventName
  • timestamp
  • eventType
  • componentId
  • sessionId
ComponentError
  • eventName
  • timestamp
  • errorCode
  • errorMessage
  • sessionId
  • componentId

eventType on ComponentLifecycleEvent is Mount or Unmount. errorCode on ComponentError can be omitted for some failures.

Card-on-file methods

Card, Apple Pay, and Google Pay withdrawals use the stored-instrument list and withdraw submit components (useCardOnFile: true).

List and edit events

Raised from the stored-instrument list while the shopper selects, edits, deletes, or abandons a card.

Event nameStructure
ChangePreselectedCardClick
  • eventName
  • timestamp
  • sessionId
  • componentId
  • pageUrl
CardDeletion
  • eventName
  • timestamp
  • cardStatus
  • cardBrand
  • sessionId
  • pageUrl
  • elementId
EditCardClick
  • eventName
  • timestamp
  • elementId
  • pageUrl
  • editedFields
  • sessionId
ComponentAbandonment
  • eventName
  • timestamp
  • sessionId
  • pageUrl
  • componentType

For stored-card abandonment, componentType is CardOnFile. The list has no CVC field, so CVVFillTime isn't raised.

Submit events

Raised when the shopper confirms a card-on-file withdrawal.

Event nameStructure
CustomerClick
  • eventName
  • timestamp
  • elementId
  • pageUrl
  • sessionId
ComponentInteraction
  • eventName
  • timestamp
  • interactionType
  • componentId
  • pageUrl
  • sessionId
  • componentType
PayButtonClick
  • eventName
  • timestamp
  • cardBrand
  • cardType
  • sessionId
  • pageUrl
  • componentId
PreAuthorisation
  • eventName
  • timestamp
  • componentType
  • sessionId
  • transactionId
  • isRetry
PostAuthorisation
  • eventName
  • timestamp
  • componentType
  • sessionId
  • transactionId
  • isRetry

On this path, componentType is typically CardOnFile, and interactionType for the submit interaction is Submit. Soft-decline retries can set isRetry to true on PreAuthorisation and PostAuthorisation.

Payout intent skips tokenisation and 3D Secure authentication analytics (e.g., PreTokenization, PostTokenization, SecurityCheck, and the authentication lifecycle events).

Closed-loop allocation

When closed-loop enforcement is active, the closed-loop drop-in also raises ComponentLifecycleEvent and ComponentError. Preferred-method and excess-selection screens reuse the card-on-file list events above when a stored-instrument list is shown.

PayPal

The PayPal panel raises ComponentLifecycleEvent and ComponentError for its UI. On submit it also raises:

Event nameStructure
CustomerClick
  • `eventName`
  • `timestamp`
  • `elementId`
  • `pageUrl`
  • `sessionId`
ComponentInteraction
  • `eventName`
  • `timestamp`
  • `interactionType`
  • `componentId`
  • `pageUrl`
  • `sessionId`
  • `componentType`

For that submit interaction, componentType is Paypal and interactionType is Submit. Card-on-file submit events such as PayButtonClick, PreAuthorisation, and PostAuthorisation apply only to card, Apple Pay, and Google Pay.

Event data

The following table describes common fields returned on analytics events.

NameDescription
browserTypeThe browser type (e.g., Chrome).
browserVersionThe browser version.
cardBrandThe card brand (e.g., Visa or Mastercard).
cardStatusThe state of the card (e.g., Expired).
cardTypeThe card type reported for the selected instrument.
componentIdThe component's unique identifier.
componentTypeThe component type (e.g., CardOnFile or Paypal).
deviceTypeThe device category detected at initialisation.
editedFieldsThe fields edited on a stored card (e.g., ExpiryDate).
elementIdThe element's unique identifier.
errorCodeThe SDK error code, when present.
errorMessageThe error description.
eventNameThe name of the event.
eventTypeThe lifecycle action (Mount or Unmount).
interactionTypeThe interaction type (e.g., Submit or Click).
isRetryWhether the lifecycle step is a soft-decline retry.
operatingSystemThe operating system.
pageUrlThe page URL where the event occurred.
sessionIdThe session's unique identifier.
timestampThe date and time when the event occurred.
transactionIdThe transaction identifier associated with the lifecycle step.