Introduction to Transaction Confirmation Events

Transaction Confirmation (TC) events are a notification service that delivers the final outcome of card transactions to interested parties, such as program managers, BIN sponsors, or third-party partners, in near-real time.

TC events are set up using webhooks which send confirmation messages when a card transaction is processed by Thredd, and the response is sent to the payment network. See Message Type Filter Codes for information on supported transaction/message types.

The below diagram shows the steps to receive TC events from Thredd.

1. The client onboards to Thredd Webhooks. See Introduction to Webhooks for more information.
2. The client uses the Create Webhook endpoint, using the 112 event code to create a TC event. See Transaction Confirmation Event for more information.
3. Configure the TC event using the Transaction Configuration endpoints. See Create Configuration for more information.
4. The client starts to receive TC events as per the configuration set up in step 3.

📘

Note

The Create Configuration endpoint only configures TC events at this time.

Transaction Confirmation Events

When you have created your webhook, you will start to receive TC events based on the configuration of your webhook. For more information on the TC events payload, see Transaction Confirmation Events and Transaction Confirmation Events - Field Descriptions.

Configuring Transaction Confirmation Events

Configuration endpoints are used for managing and applying different configuration settings for TC events, depending on the level of configuration that your institution has access to.

As a BIN Sponsor, you can configure TC events that you want to receive from Thredd for all of your Program Managers. You can choose to configure global settings (all the settings will be the same and applied to all your Program Managers' TC events that you would like to receive), or individual settings (different configurations applied for different Program Managers).

You can use and apply all the configuration options for the TC events that are available to the Self-Issuer/Program Manager level, while Self-Issuer/Program Manager will have access and be able to configure just the settings related to their own program.

The following example shows a global configuration, where an ‘Active’ status as well as a transaction/message type filter ‘0’ is set for all Program Managers’ TC events that you would want to receive from Thredd. As a result, TC events for all the Program Managers will be activated/sent, and these events will contain all the possible transaction/message types.

{
    "status": "active",
    "messageTypeFilter": [0]
}  

In the next example, the ‘Active’ status and the messageTypeFilter value of ‘1’ are set specifically against the Program Manager with the unique identifier of ‘20’. As a result, TC events will be activated/sent only for the Program Manager with ID ‘20’, and only for the transaction/message type ‘1’ - Authorisation (0100).

📘

Note

For more information on the different transaction/message types supported by TC events, see Message Type Filter Codes.

{
    "pmId": 20,
    "status": "active",
    "messageTypeFilter": [1]
}        

In this example, the ‘Active’ status and the two transaction/message type filters ‘1’ and ‘2’ are configured specifically against the Product with the unique identifier of ‘345678’. As a result, TC events will be activated/sent only for the Program Manager associated with this Product ID, and only for the transaction/message type ‘1’ - Authorisation (0100) and ‘2’ - Authorisation Advice (0120).

{
    "productId": 345678,
    "status": "active",
    "messageTypeFilter": [1, 2]
}    

In this final example, the ‘Active’ status and the transaction/message type filters ‘1’, ’2’ and ‘3’ are configured against both a certain Program Manager and a Product. As a result, TC events will be activated/sent only for the Program Manager with ID = ‘20’, only for their Product ID = “345678”, and only for transaction/message type ‘1’ - Authorisation (0100), ‘2’ - Authorisation Advice (0120) and ‘3’ - Online Financial Request (0200).

{
    "pmId": 20,
    "productId": 345678,
    "status": "active",
    "messageTypeFilter": [1, 2, 3]
}

As a Self-Issuer/Program Manager, you can configure settings related to your program and apply them to your Products (Product IDs) only.

The following example shows a global configuration, where an ‘Active’ status as well as a transaction/message type filter ‘0’ is set for all your Products. As a result, TC events for all the Products will be activated/sent to you by Thredd, and these events will contain all the possible transaction/message types.

{
    "status": "active",
    "messageTypeFilter": [0]
}  

In the next example, the ‘Active’ status and the transaction/message type filters ‘1’ and ‘2’ are configured specifically against the Product with the unique identifier of ‘345678’. As a result, TC events will be activated/sent to you by Thredd only for the Product ID = ‘345678’ and only for transaction/message type ‘1’ - Authorisation (0100) and ‘2’ - Authorisation Advice (0120).

{
    "productId": 345678,
    "status": "active",
    "messageTypeFilter": [1, 2]
}    

Message Type Filter Codes

When configuring TC events, you can choose the transaction/message types that you receive. The following table describes each code and the associated transaction/message types.

Configuration Endpoints

The following Configuration Endpoints can be used to create and manage TC events:

• Create Configuration enables you to create a configuration for a webhook event subscription. See Create Configuration.
• List Configuration enables you to retrieve all configurations at your registered level. See List Configurations.
• Update Configuration enables you to update a configuration. See Update Configuration
• Update Configuration Status enables you to update the status of a configuration. See Update Configuration Status.
• Delete Configuration enables you to delete a configuration. See Delete Configuration
• Get Configuration by Config ID enables you to return the details of a specific configuration. See Get Configuration by Config ID.

Transaction Confirmation Onboarding

To use TC events, you must first successfully onboard to Thredd's webhooks. For more information, see Accessing the API Hub with mTLS and Introduction to Webhooks.

Integrate with Webhook Services

You need to set up the following configuration when integrating with Thredd's webhooks.

• Scopes: eds.read and eds.write
• Custom Claim: issuerid = <Issuer Bank Master ID>

📘

Note

When using API Hub, we recommend including the region in the payload request header. Select from the following regions:

• Use 0 for the Default environment
• Use 1 for the EMEA environment
• Use 2 for the APAC environment

Register Webhook

You must register your webhook to use the Transaction Configuration endpoint. For more information on creating a webhook, see Create and View Webhooks.

The below example displays a sample payload for registering TC events.

{
  "events": [112],
  "webhookStatus": "active",
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "key 1": "Value 1"
    }
  }
}

Whitelisting Thredd IP Addresses

You must white list the following IP addresses for each environment to ensure successful event delivery: