Skip to main content

Events

The Drop-in emits events for key lifecycle moments. Use events to respond to initialization status and errors.

Setting Up an Event Listener

Pass an eventListener function when creating the Drop-in:

const dropin = await Purse.createDropinCheckout({
session: clientSession.widget.data,
eventListener: (event) => {
console.log(event.code, event.payload);
}
});

Public Events

The Drop-in exposes two events through the eventListener callback:

ready

Emitted when the Drop-in is fully initialized and ready for user interaction.

Event structure:

{
code: "ready";
payload: undefined;
}

Typical use:

  • Hide loading indicators
  • Display the payment form container

Example:

eventListener: (event) => {
if (event.code === "ready") {
document.getElementById("loading-spinner").style.display = "none";
document.getElementById("checkout-container").style.display = "block";
}
}

error

Emitted when an error occurs during initialization or operation.

Event structure:

{
code: "error";
payload: {
message: string;
code?: string;
};
}

Typical use:

  • Display an error message to the user
  • Log the error for debugging

Example:

eventListener: (event) => {
if (event.code === "error") {
console.error("Drop-in error:", event.payload.message);
showErrorNotification(event.payload.message);
}
}

Complete Example

const dropin = await Purse.createDropinCheckout({
session: clientSession.widget.data,
eventListener: (event) => {
switch (event.code) {
case "ready":
document.getElementById("loading-spinner").style.display = "none";
break;

case "error":
console.error(event.payload);
document.getElementById("error-message").textContent = event.payload.message;
document.getElementById("error-message").style.display = "block";
break;
}
}
});

isPaymentFulfilled

The Drop-in exposes an isPaymentFulfilled property — a reactive store that indicates whether the user has selected a valid payment method and the payment amount is covered.

Use this to enable or disable your pay button:

const payButton = document.getElementById("pay-button");

dropin.isPaymentFulfilled.subscribe((isFulfilled) => {
payButton.disabled = !isFulfilled;
});
Reactive Store

isPaymentFulfilled follows a simple subscribe pattern. Call subscribe() with a callback function to receive updates when the value changes.

Next Steps