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​