Skip to main content

Listening to Payment Success Event

You may want to track payments made by the end user, for example, for auditing purposes.


Prior to version 2.2, it was only possible for ATSs integrating with the HAPI Backend using the Payment Widget it provides.


HAPI Elements now supports ability to pass a success callback URL of your backend as a webhook so that HAPI Backend calls the webhook when payment is successful.


This success callback is useful for tracking payments made by the end user using Wallet Balance and Direct Charge. There is no payment being done when using Purchase Order thus your webhook will not be called. If you want to track Purchase Orders, please refer to Purchase Order documentation.

Setting the paymentIntentSuccessCallbackUrl​

Via hapiInjector​

If you are using the hapiInjector as stated in Getting Started page, then you can do the following:

const onLoadHapiElementsInjector = async (clientToken: string) => {
    try {
        window.hapiInjector.setConfig("clientToken", clientToken)
        // Inject is a Promise that resolves when HAPI Elements script has successfully loaded
        await window.hapiInjector.inject()
        // You can now start using HAPI Elements Javascript API
        console.log('[HAPI] Elements has loaded', window.hapi)
        // set paymentIntentSuccessCallbackUrl
        window.hapi.wallet.state.paymentIntentSuccessCallbackUrl = "https://my-ats.com/api/hapi-payment-success-callback-webhook"
    } catch (error) {
        console.error(error)
    }
}

Via hapi:load:script event​

If you are using the hapi:load:script event as stated in Getting Started page, then you can do the following:

const onLoadHapiElements = () => {
    console.log('[HAPI] Elements has loaded', window.hapi)
    window.hapi.wallet.state.paymentIntentSuccessCallbackUrl = "https://my-ats.com/api/hapi-payment-success-callback-webhook"
}

window.addEventListener("hapi:load:script", onLoadHapiElements)

Understanding how paymentIntentSuccessCallbackUrl will be called​

When the end user either does a wallet balance top-up or a campaign order using direct charge, HAPI Elements will append some query parameters to the URL you passed, so that you can use those parameters on your backend to differentiate payments.


The URL will look like:

https://my-ats.com/api/hapi-payment-success-callback-webhook
    ?your-custom-query-parameter=some-value
    // draftCampaignId only exists for direct charge campaign orders
    // it does not exist for wallet balance top-ups
    &draftCampaignId=some-draft-campaign-id
    &amount=1000
    &walletId=some-wallet-id

When a payment is successful via Wallet Balance and Direct Charge, there will be a POST request made to the specified webhook URL. The POST body will look as such:

{
    "id": 1
}

The POST payload should be ignored as it does not contain any useful information however the URL will include query parameters that HAPI Elements adds as specified above. On your backend, you can use the query parameters HAPI Elements added to differentiate payments.


info

When passing the webhook URL of your backend, you can include custom query parameters in the URL if needed. There are a couple of reserved query parameter keys which cannot be used:

  • draftCampaignId
  • amount
  • walletId

Differentiating a wallet balance top-up versus a direct charge campaign order​

When the webhook is called via POST, it may contain draftCampaignId. If it contains, then it is a direct charge campaign order, otherwise it is a wallet balance top-up.