sd-payment-success JavaScript Custom Event

Overview

The sd-payment-success event is a JavaScript CustomEvent dispatched on a SureDonation form after a payment gateway confirms a successful payment on the frontend.

This event allows developers to execute custom JavaScript, such as tracking conversions, displaying animations, triggering third-party integrations, or performing custom redirects, immediately after a successful donation without modifying the SureDonation core plugin.

How It Works

The sd-payment-success event is currently dispatched by the PayPal payment gateway.

Since PayPal completes the payment using its own PayPal Buttons interface instead of the form’s normal submission flow, SureDonation dispatches this custom event after the payment has been successfully verified and captured on the server.

Event Behavior

The event is dispatched as a standard DOM CustomEvent with the following properties:

Because the event bubbles through the DOM, you can listen for it on:

• The specific donation form
• A parent container
• The document

Event Data

The event payload is available through event.detail.

Listening for the Event

You can listen for the event globally on the document.

document.addEventListener('sd-payment-success', (event) => {

    const {
        gateway,
        donationId,
        orderId,
        captureId,
        message,
    } = event.detail;

    console.log(`Donation #${donationId} succeeded via ${gateway}`);

    // Example: Send analytics event
    if (window.gtag) {

        window.gtag('event', 'donation_complete', {
            transaction_id: orderId,
            gateway,
        });

    }

});

document.addEventListener('sd-payment-success', (event) => {

    const {
        gateway,
        donationId,
        orderId,
        captureId,
        message,
    } = event.detail;

    console.log(`Donation #${donationId} succeeded via ${gateway}`);

    // Example: Send analytics event
    if (window.gtag) {

        window.gtag('event', 'donation_complete', {
            transaction_id: orderId,
            gateway,
        });

    }

});

Listening on a Specific Form

Because the event bubbles, you can also listen only on a specific SureDonation form.

const form = document.querySelector('.sd-form-container form');
form.addEventListener('sd-payment-success', (event) => {

    // Handle successful donation for this form.

});

const form = document.querySelector('.sd-form-container form');
form.addEventListener('sd-payment-success', (event) => {

    // Handle successful donation for this form.

});

Default SureDonation Behavior

SureDonation includes its own frontend listener (initFormSubmission) that responds to the sd-payment-success event by calling the internal showSuccessMessage() method.

Depending on your campaign settings, SureDonation will automatically:

Redirect the Donor

If the campaign uses the Redirect confirmation type and a valid redirectUrl is configured, the donor is redirected after a successful payment.

For security reasons, invalid URLs, including protocol-relative URLs and non-HTTP(S) URLs, are rejected.

Display the Success Message

If no redirect is configured, SureDonation:

• Hides the donation form.
• Inserts the success message into .sd-success-box-description.
• Displays the success message container.
• Scrolls the page to the success message.

Common Use Cases

The sd-payment-success event can be used for:

• Tracking Google Analytics or GA4 conversions
• Sending Meta Pixel or other advertising events
• Triggering custom JavaScript integrations
• Displaying confetti or celebration animations
• Updating custom UI elements
• Running post-donation workflows
• Integrating with third-party frontend applications

Related Hooks