> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Event Webhook

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](#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

<Note>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.</Note>

## Supported Message Categories

* We send all authorisation message types via the [Transaction Event Webhook](https://nextgen-docs.enfuce.com/api/transaction-lifecycle/transaction-event/transaction-event-webhook-openapi).

<Info>For more information on what each message type implies, see [Authorisation Message Types](https://nextgen-docs.enfuce.com/guides/transaction-lifecycle/authorisation/authorisation-types-transaction-flows).</Info>

* 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.

  <Note>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.</Note>

## 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:

<AccordionGroup>
  <Accordion title="Request">
    <div style={{ marginLeft: '20px' }}>
      When `messageFunction` = `REQUEST`, the Scheme requires a response from the processor indicating whether the payment is approved or declined.
    </div>
  </Accordion>

  <Accordion title="Advice">
    <div style={{ marginLeft: '20px' }}>
      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.
    </div>
  </Accordion>

  <Accordion title="Notification">
    <div style={{ marginLeft: '20px' }}>
      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.
    </div>
  </Accordion>
</AccordionGroup>

## 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**:

```mermaid placement="top-right" theme={null}
  sequenceDiagram

    autonumber

    participant Enfuce
    participant Ledger

    rect rgb(230, 245, 255)
    note right of Enfuce: `INITIAL_AUTHORIZATION` — Authorisation Request API (Synchronous)
    Enfuce->>Ledger: Sends authorisation request
    Ledger->>Ledger: Validate transaction & decide
    Ledger-->>Enfuce: Approve/Decline/Partially approve the request
    Ledger->>Ledger: Adjust ledger balance
    end

    rect rgb(240, 240, 240)
    note right of Enfuce: `INITIAL_AUTHORIZATION` (`messageFunction`: `ADVICE`) - Transaction Event Webhook (Asynchronous)
    Enfuce->>Ledger: Sends webhook notifications
    Ledger->>Ledger: Processes event
    Ledger-->>Enfuce: Sends HTTP response codes to indicate acknowledgement
    Ledger->>Ledger: Adjust ledger balance, if required
    End

```

### 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`

| Interface                 | Message Function | Action                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorisation Request API | `REQUEST`        | Verify the cardholder's account balance and approve/decline/partially approve the request. Send your response within 5 seconds.                                                                                                                                                                                                                          |
| Transaction Event Webhook | `ADVICE`         | The transaction was approved by the Scheme in the STIP mode and no authorisation message was previously sent. Hence, hold the amount represented in the `transaction.approvedAmount` attribute. Respond with HTTP response codes to indicate acknowledgement. <Note>Put the amount on hold, if the `transactionType` is any value, except credit.</Note> |

## 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:

| Parameter                         | Description                                                                                                                                                                                                                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card.id`                         | Unique identifier of the card assigned by Enfuce, used for the specific transaction.                                                                                                                                                                                                                                       |
| `card.accountId`                  | Unique identifier of the account assigned by the ledger, associated with the specific card used for the transaction.                                                                                                                                                                                                       |
| `id`                              | Unique identifier of the message being sent. This is referenced only by `VOID_AUTHORIZATION`.                                                                                                                                                                                                                              |
| `transactionId`                   | Enfuce generated unique ID to identify each card transaction. Related messages contain the same transaction ID to indicate association with the same transaction.                                                                                                                                                          |
| `messageCategory`                 | Categorises the authorisation message, based on the current processing state, for example, `INITIAL_AUTHORIZATION` or `INCREMENTAL_AUTHORIZATION`. For more information on authorisation message categories, see [Authorisation Types](/guides/transaction-lifecycle/authorisation/authorisation-types-transaction-flows). |
| `merchant.partialApprovalCapable` | Indicates whether the merchant accepts partial approval — if this flag is set, you can partially approve a request (the decision depends on the cardholder's account balance).                                                                                                                                             |
| `transaction.transactionType`     | Indicates the type of transaction, for example, `RETAIL` or `CREDIT`.                                                                                                                                                                                                                                                      |
| `transaction.approvedAmount`      | Indicates the amount that can be approved after spend control limiters have been applied. If the merchant accepts partial authorisations, the approved amount can be less than the billing amount; otherwise, the value in the `transaction.approvedAmount` parameter is equivalent to the `billingAmount`.                |

## 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`:

<AccordionGroup>
  <Accordion title="INITIAL_AUTHORIZATION">
    <Accordion title="Message Function | `REQUEST`">
      <div style={{marginLeft:'30px'}}>
        <p>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.</p>

        **Actions**:

        <ul>
          <li>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.</li>
          <li>Return HTTP response code to indicate acknowledgement of webhook receipt.</li>
        </ul>
      </div>
    </Accordion>

    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft:'30px'}}>
        <p>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.</p>

        | Conditions                                  | Actions                                                                                                       |
        | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
        | `transactionType`: any value, except credit | Hold the amount represented in the `transaction.approvedAmount` attribute.                                    |
        | `transactionType` = `CREDIT`                | No action <Note>To avoid any risk, do not credit the cardholder’s account until the credit is cleared.</Note> |
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="INCREMENTAL_AUTHORIZATION">
    <Accordion title="Message Function | `REQUEST`">
      <div style={{marginLeft:'30px'}}>
        <p>This message is sent asynchronously to explain what happened.</p>

        **Actions**:

        <ul>
          <li>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.</li>
          <li>Return HTTP response code to indicate acknowledgement of webhook receipt.</li>
        </ul>
      </div>
    </Accordion>

    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft:'30px'}}>
        <p>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.</p>

        **Actions**

        * Hold the amount represented in the `transaction.approvedAmount` attribute.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="DECLINED_AUTHORIZATION">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>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.</p>

        **Actions**:

        * No action required.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="ADJUSTMENT">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>This message is sent asynchronously to inform that a card transaction has been adjusted or partially reversed.</p>

        | Conditions                                  | Actions                                                                                                                                                                              |
        | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
        | `transactionType`: any value, except credit | Identify the associated authorisation messages, based on the `transactionId`. Update the amount previously put on hold to the value represented in the `transaction.approvedAmount`. |
        | `transactionType`: `CREDIT`                 | No action <Note>To avoid any risk, do not credit the cardholder’s account until the credit is cleared.</Note>                                                                        |
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="REVERSAL">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>This message is sent asynchronously to inform that a card transaction has been fully reversed.</p>

        **Actions**:

        * Identify the associated authorisation message, based on the `transactionId`, and reverse the amount that was previously put on hold.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="BALANCE_ENQUIRY">
    <Accordion title="Message Function | `REQUEST`">
      <div style={{marginLeft: '30px'}}>
        <p>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.</p>

        **Actions**:

        * No action required.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="PIN_MANAGEMENT">
    <Accordion title="Message Function | `REQUEST`">
      <div style={{marginLeft: '30px'}}>
        <p>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.</p>

        **Actions**:

        * No action required.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="PIN_MANAGEMENT_REVERSAL">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>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`.</p>

        | Conditions                                       | Actions                                                                                                                              |
        | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
        | `transaction.approvedAmount` is greater than `0` | Identify the associated PIN management request, based on the `transactionId`, and remove the amount that was previously put on hold. |
        | `transaction.approvedAmount` = `0`               | No action required.                                                                                                                  |
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="PURGE_AUTHORIZATION">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>This message is sent asynchronously to inform that an account block has expired and hence, must be removed.</p>

        **Actions**:

        * Identify the associated authorisation message, based on the `transactionId` and remove the amount that was previously put on hold.
      </div>
    </Accordion>
  </Accordion>

  <Accordion title="VOID_AUTHORIZATION">
    <Accordion title="Message Function | `ADVICE`">
      <div style={{marginLeft: '30px'}}>
        <p>This message is sent asynchronously if Enfuce did not receive any valid response from the ledger to any authorisation request.</p>

        **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.
      </div>
    </Accordion>
  </Accordion>
</AccordionGroup>

## 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.