Widget Events

The Master Widget in the checkout flow triggers specific events to inform merchants about the status of a customer's checkout session.

These events are essential to managing the cardholder experience, catering for the possible outcomes of checkout session such as: successful payment, payment failure/error or expired session.

onPaymentSuccessful

Description

This event is triggered when a payment is completed successfully. It allows the merchant to execute specific actions, such as updating the order status, notifying the customer of the successful transaction, and/or redirecting the customer to a confirmation page.

When it is triggered

• This event occurs immediately after the payment gateway confirms that the payment has been processed successfully.

Event payload

• intent_id: The unique identifier of the payment intent.
• charge_id: The unique identifier of the charge that was created as a result of the payment workflow.

Example Usage

widget.onPaymentSuccessful(function (data) {
    console.log("success: ", data)
    // Handle successful payment
    // - Update order status
    // - Redirect to confirmation page
    // - Send confirmation email
});

onPaymentError

Description

This event is triggered when a payment fails. Merchants can use this event to handle payment errors, such as displaying error messages to customers or logging the error details.

When it is triggered

• This event is fired when the payment gateway reports a failure during the payment process or any unexpected error scenarios during the Checkout session.

Event payload

• intent_id: The unique identifier of the payment intent.
• charge_id: The unique identifier of the charge that was created as a result of the payment workflow (if it was created before the error).

Example Usage

widget.onPaymentFailure(function (error) {
    console.log("failure: ", error)
    // Handle payment failure
    // - Display error message to user
    // - Log error details
    // - Offer retry options
});

onPaymentExpired

Description

This event is triggered when a payment workflow session expires. This typically happens if the customer takes too long to complete the payment (e.g after 15 minutes of inactivity).

When it is Triggered

• The event is triggered when the session timeout is reached, and the payment is no longer valid.

Event Payload

• intent_id: The unique identifier of the payment intent.
• charge_id: The unique identifier of the charge that was created as a result of the payment workflow (if created before the session expiration).

Example Usage

widget.onPaymentExpired(function (data) {
    console.log("expired: ", data)
    // Handle payment expiration
    // - Inform user that session has expired
    // - Offer to restart checkout process
    // - Generate new intent token
});

Complete Event Handling Example

var widget = new cba.Checkout('#widget', "{{intent_token}}");

widget.onPaymentSuccessful(function (data) {
    console.log("Payment successful: ", data);
    // Redirect to success page or update UI
    window.location.href = '/payment-success';
});

widget.onPaymentFailure(function (error) {
    console.log("Payment failed: ", error);
    // Show error message to user
    alert('Payment failed. Please try again.');
});

widget.onPaymentExpired(function (data) {
    console.log("Payment expired: ", data);
    // Inform user and offer to restart
    alert('Payment session expired. Please refresh to try again.');
});