Setup Events

Setup Request Events are webhook notifications from GETTRX One that provide real-time updates on setup intents. A setup intent represents a process to prepare a payment method for future use, enabling merchants to securely store and use payment methods for recurring billing or on-demand charges.

By subscribing to these events, you can monitor the lifecycle of setup intents and build seamless workflows for managing payment method storage and readiness.

Key Setup Request Webhook Events

Setup Request Succeeded (setup_request.succeeded)

Indicates that the setup intent has been successfully completed. The payment method is now validated and ready to be used for future transactions.

{
    account: "acm_65f48b068b8d6912fe07f000",
    attemptId: "wha_6751e4a4ebc1dcbd0b339295",
    created: "1733379216",
    "data": {
        "object": {
            id: "setr_675144631b260933080d90ae",
            created: 1733379171,
            customer: "cus_66e34169c4cbbf37be2f3997",
            description: "Veniam creta taceo utor.",
            setupAttempt: "setatt_675144630788034b8605032d",
            paymentMethod: "pm_675144631b260933080d90ad",
            setupFutureUsage: "on_session",
            status: "successful",
            object: "setup_request"
        }
    },
    id: "evt_67514490891a560145e26782",
    object: "event",
    "request": {},
    type: "setup_request.succeeded"
}

Setup Request Failed (setup_request.failed)

Sent when a setup intent is failed, either by the customer, merchant, or system. This event ensures your system reflects the cancellation and stops any associated workflows.

{
    account: "acm_65f48b068b8d6912fe07f000",
    attemptId: "wha_67994d8ae72b0ef46f391098",
    created: "1738100105",
    "data": {
        "object": {
            id: "setr_67994d8787bddd1a8d4e74fd",
            created: 1738100103,
            customer: "cus_66e34169c4cbbf37be2f3997",
            description: "Claudeo advenio iusto capio.",
            lastSetupError: null,
            setupAttempt: "setatt_67994d87fa47c02065b8bec3",
            metadata: null,
            onBehalfOf: null,
            paymentMethod: "pm_67994d8787bddd1a8d4e74fc",
            setupFutureUsage: "on_session",
            status: "failed",
            object: "setup_request"
        }
    },
    id: "evt_67994d89527fca485281b85f",
    object: "event",
    "request": {},
    type: "setup_request.failed"
}

Best Practices for Setup Request Events

Track Payment Method Readiness:

Use setup_request.succeeded to confirm when a payment method is validated and ready for use. Notify merchants or customers of successful setup intents to enhance communication and transparency.

Handle Cancellations Gracefully:

Leverage setup_request.failed to stop associated workflows and notify stakeholders. Provide merchants or customers with the option to retry or resolve issues that led to failure.

Automate Workflows:

Use setup_request.created to trigger any necessary pre-validation processes or notifications. Integrate these events into billing systems to ensure payment methods are available for future transactions.

Improve User Experience:

Notify customers when their payment method setup is successful or failed to keep them informed. Provide proactive solutions if a setup intent fails.

By subscribing to Setup Request Events, you can streamline the management of stored payment methods, improve customer experience, and ensure operational efficiency for merchants.