Events & callbacks

Lifecycle

Event	How to listen	Description
`PaymentSDKReady`	`window.addEventListener('PaymentSDKReady', …)`	The loader script finished loading and `window.PaymentSDK` is available.
`onReady`	Config callback	The iframe is mounted and the form can receive input.
`onError`	Config callback	Configuration error or the card form could not load. `{ message: string }`

`onMessage`

onMessage receives one of these messages:

type SdkMessage =
  | { type: 'success'; detail: CheckoutResponse }
  | { type: 'error'; message: string }
  | { type: 'PAYMENT_3DS_START' }
  | { type: 'PAYMENT_3DS_SUCCESS' }
  | { type: 'PAYMENT_3DS_FAILURE' };

type CheckoutResponse = {
  sessionId: string;
  code: 'OK' | 'ALREADY_SUBSCRIBED';
  message: string;
  customerId: string | null;
};

`success`

The API accepted the checkout. Always check detail.code:

`detail.code`	Meaning	Suggested action
`OK`	Customer created and payment processed.	Redirect to your thank-you page. Grant access when the `TRANSACTION` webhook arrives.
`ALREADY_SUBSCRIBED`	This email + card already has an active subscription to this product.	Tell the buyer they are already subscribed.

{
  "type": "success",
  "detail": {
    "sessionId": "3f6c2b8e-1d2a-4c55-9a3e-7b1f0c9d2e41",
    "code": "OK",
    "message": "The process completed successfully.",
    "customerId": "5812"
  }
}

`error`

The checkout couldn’t be completed (invalid card, expired session, product unavailable…). message is a buyer-friendly text you can display. The detailed reason is available in the API error codes.

{ "type": "error", "message": "We could not process the payment. Please try again." }

3-D Secure events

PAYMENT_3DS_START, PAYMENT_3DS_SUCCESS and PAYMENT_3DS_FAILURE report the progress of a 3-D Secure authentication. They are informational: don’t treat them as a final result.