Skip to main content
Transaction event webhooks are asynchronous notifications that Enfuce sends to a ledger; this is done only to inform about transaction lifecycle events that have already occurred. If the ledger does not respond to the notifications, we will retry to deliver them. For some message types, the ledger might need to adjust the ledger balance if it is impacted; this is based on the content of the webhook (for example, the message category, message function, and the conditions). For more information on what actions you must perform, see Ledger’s Actions.

​
Webhook Recipients

The transaction event webhook is usually sent to the following receivers:
  • Applications that manage your ledger balance: They must authorise and approve the transactions.
  • Applications that send notifications to your cardholders’ devices.
  • Data warehouse feeds
To receive the messages, you must provide your customer success manager with the specific endpoint URLs and the HTTP basic authentication credentials required to access the endpoints.

​
Supported Message Categories

For more information on what each message type implies, see Authorisation Message Types.
  • In addition, we also send the FINANCIAL message category, which is similar to a clearing message of batch payments. A transaction event webhook of FINANCIAL message category includes the same contents as delivered in a clearing file copy.
    Supporting FINANCIAL messages sent via the transaction event webhook is an additional option because the same information is available in the clearing file copy, allowing you the flexibility to exclude this message category from Transaction Event Webhooks during configuration.

​
Supported Message Functions

The messageFunction does not indicate whether Enfuce requires any approval from the ledger. Instead, it describes the interaction and expected behaviour between the payment Scheme and Enfuce. When we forward the message to the ledger, we maintain the same messageFunction as received from the Scheme. The transaction event webhook supports the following message functions:
When messageFunction = REQUEST, the Scheme requires a response from the processor indicating whether the payment is approved or declined.
When messageFunction = ADVICE, the Scheme message represents an event that has already occurred and therefore cannot be declined. However, the Scheme still requires an acknowledgement confirming that the message was received successfully.
When messageFunction= NOTIFICATION, the Scheme sends the message for informational purposes only and does not expect any response or acknowledgement. This message type is typically used for file-based messages, such as clearing messages.

​
Difference between Authorisation Request API and Transaction Event Webhook

Here is a diagrammatic representation that illustrates how you must manage the same message category — INITIAL_AUTHORIZATION when received via two the different interfaces — Authorisation Request API and Transaction Event Webhook:

​
Example

Here is an example that explains how you differently manage the same authorisation message, when you receive it via Authorisation Request API versus Transaction Event Webhook: Message category: INITIAL_AUTHORIZATION

​
Webhook Contents

The Authorisation Request API endpoint includes rich information about a transaction. The following lists the minimum data you require to arrive at a decision:

​
Ledger’s Actions

The following section explains the actions that you must take when you receive a message via the the Transaction Event Webhook interface for any of the following messageCategory along with their corresponding messageFunction:

This message is sent asynchronously to explain what happened. The webhook is usually generated after an INITIAL_AUTHORISATION request sent via the Authorisation Request API interface is approved/declined/partially approved by the ledger.

Actions:
  • Does not need to take any action, as an authorisation amount is already held when INITIAL_AUTHORIZATION message is sent via the Authorisation Request API and is approved by the ledger.
  • Return HTTP response code to indicate acknowledgement of webhook receipt.

This message is sent asynchronously to explain what happened. In this scenario, no INITIAL_AUTHORIZATION request is previously sent via the Authorisation Request API interface as the Scheme has approved the request in the STIP mode.

This message is sent asynchronously to explain what happened.

Actions:
  • Does not need to take any action, as authorisation amount is already held when INITIAL_AUTHORIZATION message is sent via the Authorisation Request API and is approved by the ledger.
  • Return HTTP response code to indicate acknowledgement of webhook receipt.

This message is sent asynchronously to explain what happened. In this scenario, no INCREMENTAL_AUTHORIZATION request is previously sent via the Authorisation Request API interface as the scheme has approved the request in the STIP mode.

Actions
  • Hold the amount represented in the transaction.approvedAmount attribute.

This message is sent asynchronously to inform that an authorisation request has been declined, and no authorisation message was previously sent. This happens when the scheme has declined the request in the STIP mode.

Actions:
  • No action required.

This message is sent asynchronously to inform that a card transaction has been adjusted or partially reversed.

This message is sent asynchronously to inform that a card transaction has been fully reversed.

Actions:
  • Identify the associated authorisation message, based on the transactionId, and reverse the amount that was previously put on hold.

This message is sent asynchronously to explain what occurred. The webhook is usually sent after an INITIAL_AUTHORISATION message is sent via the Authorisation Request API interface and the ledger has either approved or declined the request.

Actions:
  • No action required.

This message is sent asynchronously to explain what occurred. The webhook is usually sent after an INITIAL_AUTHORISATION message is sent via the Authorisation Request API interface and the ledger has either approved or declined the request.

Actions:
  • No action required.

This message is sent asynchronously to inform that a PIN management request has been reversed. If any fee was incurred for PIN related services, the transaction.approvedAmount must be greater than 0.

This message is sent asynchronously to inform that an account block has expired and hence, must be removed.

Actions:
  • Identify the associated authorisation message, based on the transactionId and remove the amount that was previously put on hold.

This message is sent asynchronously if Enfuce did not receive any valid response from the ledger to any authorisation request.

Actions:
  • Identify the associated authorisation request message, based on the id of the original message (in the VOID_AUTHORIZATION webhook, the referenceEventId parameter specifies the specific transaction event identifier that must be cancelled); remove any amount that was previously put on hold.

​
Guaranteed Webhook Delivery

We have a guaranteed delivery process, where we resend the webhook notifications, if the ledger is unavailable. Enfuce retries over the next 24 hours, up to 185 times.