Webhook Event Codes

The following page describes each of the event codes available as part of Thredd's Event Delivery Service.

Event Code 101 - Fraud Rule Triggered by a Transaction

📘
Note
To use this event code, you must be onboarded for Fraud Transaction Monitoring, and have valid fraud rules set up. For more information, speak to your Account Manager.

The 101 event code is used to send out a message when a fraud rule is triggered by a transaction.

{ 
  "productId": 12345,
  "events": [101],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a fraud rule is triggered by a transaction, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 101,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "fraudAlertId": "05e991e3-9058-4d79-bf01-76d4e8fe2059",
    "productId": 123,
    "transactionId": 98765432101212,
    "tokenId": 545454121,
    "transactionAmount": "50.75",
    "currency": "USD",
    "merchantName": "Sample Merchant",
    "location": "United Kingdom",
    "dateTime": "2024-01-24T14:30:00Z",
    "mcc": "4567",
    "notificationMessageContent": "Did you attempt $50.75 on card ending 1234 at Example Merchant ? We suspect fraud and blocked the card, Acknowledge if you made this purchase."
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 101.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
fraudAlertId	Unique identity of the fraud alert.
productId	The product identifier.
transactionId	Unique identifier of the transaction.
tokenId	The public token of the cardholder.
transactionAmount	The amount of the transaction.
currency	The currency of the transaction.
merchantName	The name of the merchant.
location	The location of the merchant where the transaction occurred.
dateTime	The date and time of the transaction in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
mcc	The Merchant Category Code (MCC) of the merchant.
notificationMessageContent	The content of the message sent to the customer.

Event Code 102 - Closing a Fraud Alert

📘
Note
To use this event code, you must be onboarded for Fraud Transaction Monitoring, and have valid fraud rules set up. For more information, speak to your Account Manager.

The 102 event code is used to send out a message when a fraud alert is closed.

{
  "productId": 12345,
  "events": [102],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a fraud alert is closed, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 102,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "fraudAlertId": "05e991e3-9058-4d79-bf01-76d4e8fe2059",
    "fraudAlertType": "Acknowledgement",
    "notificationMessageContent": "From Bank: Thank you for replying. Your card ending 1234 has been unblocked.",
    "productId": 123
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 102.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
fraudAlertId	The unique identity of the fraud alert.
fraudAlertType	The type of fraud acknowledgement. For example, `Timeout` or `Acknowledgment`.
notificationMessageContent	The content of the message sent to the customer.
productId	The product identifier.

Event Code 103 - Card Status Change

📘
Note
Event Code 103 (Card Status Change) sends notifications asynchronously only, as messages are processed in batches. Clients will not receive notifications in a specific order. If a client requires ordered processing, you must use the notification timestamp provided in the payload to ensure proper sequencing.

The 103 event code is used to send out a message when a card status is changed.

{
  "productId": 12345,
  "events": [103],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a card status is changed, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 103,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"tokenId": "123456789",
"productId": 123,
"dateTime": "2024-01-24T14:30:00Z",
"newCardStatus": "41",
"oldCardStatus": "00",
"message": "Card status changed from active to lost or stolen.",
"trackingId": "60b83k64-526e-4d25-84c7-32b6e47c02b3"
}
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 103.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
tokenId	The public token of the cardholder.
productId	The product identifier.
dateTime	The date and time the status for the card changed. In the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
newCardStatus	The current status of the card.
oldCardStatus	The previous status of the card.
message	The card status change reason message created by Thredd based on the new card status and old card status.
trackingId	The Unique identifier generated by Thredd for tracking.

Event Code 104 - Custom PAN Creation

📘
Note
The ability to create a card with a custom PAN is a chargeable service. Contact your Account Manager if you're interested in creating cards with a custom PAN.
For more information on creating a custom PAN, see Customisable Card Number.

The 104 event code is used to send out a message a card with a Custom PAN has been created.

{ 
  "productId": 12345,
  "events": [104],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a card with a Custom PAN has been created, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 104,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "productId": 123,
    "messageId": "60b83k64-526e-4d25-84c7-32b6e47c02b3",
    "publicToken": "123456789"
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
productId	The product identifier.
messageId	A unique Guid generated by Thredd.
publicToken	The public token of the cardholder.

Event Code 105 - Customer Alert to Potential Scam

📘
Note
You must be onboarded for Scam Transaction Monitoring, and have set up scam alerts, to use this event code. For more information, speak to your Account Manager.

The 105 event code enables you to action your pending payments based on the outcome of a manual review in Fraud Transaction Monitoring. When the webhook service has been successfully set up, notifications will be sent when:

There is a payment event only. For example, a non-card event
An incident is reviewed (one message per alert reviewed) and set to Risk or No Risk

See the below example of a webhook for a 105 event code.

{
  "programManagerCode" : "TRD",  
  "productId": 12345,
  "events": [105],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a potential scam has been flagged, a notification response is sent from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "programManagerId": 16,
    "eventCode": 105,
    "eventVersion": "v1",
    "notificationTime": "2024-11-24T11:20:28Z",
  },
  "payload": 
   {
      "transactionId": "123412341234",
      "eventid": "55221979-a4cd-4d7a-bb0c-1b3f0b7cb92c",
      "reviewStatus": "no-risk",
      "reviewDate": "2024-11-24T09:15:10.086Z"
   },
  "messageHeaders": {
    "schemaId": 1
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 105.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
transactionId	The unique identifier for the transaction. It can be used to link different messages as part of the same transaction (for example, payment request and confirmation messages).
eventid	The unique reference for the event. This reference string should be fully unique across the entire system.
reviewStatus	The review of the potential scam from Scam Transaction Monitoring. For example, "no-risk".
reviewDate	When an analyst reviewed the potential scam in Scam Transaction Monitoring.
messageHeaders	Object containing the message headers.
schemaId	The schema identifier. This is always `1`. Note that this is a Scam Transaction Monitoring config setting passed on in the response, and no client action is needed.

Event Code 106 - Tokenisation Authorisation Request (TAR)

The 106 event code is used to send out a Tokenisation Authorisation Request (TAR).

{
  "productId": 12345,
  "events": [106],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a TAR has been made, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 106,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"publicToken": "123456789",
"productId": "124",
"paymentToken": "987654321",
"dpan": "5168563000002547",
"networkTokenReference": "67024958022",
"provisioningTraceId": "VIS1-20210318-381077544887139",
"tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
"processorDateTime": "2024-10-29T15:16:50Z",
"responseCode": "85",
"requestSource": "MOBILE_BANKING_APP",
"tokenRequestorId": "1234",
"orangeFlowIndicator": true
}
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
publicToken	The public token associated with the TAR notification.
productId	The unique identifier of the product.
paymentToken	Thredd's internal identifier for the payment token.
dpan	The DPAN identifier for the payment token.
networkTokenReference	The unique token reference from the network.
provisioningTraceId	The lifecycle identifier to link tokenisation events that are related.
tokenisationServiceDateTime	The event generation timestamp from the tokenisation service.
processorDateTime	The event processing timestamp from Thredd.
responseCode	Identifies the action taken by Thredd for the tokenisation request: 00 - Unconditional approval 85 - Conditional approval 05 - Generic Decline N7 - CVV2 Failure 14 - Invalid PAN 54 - Invalid Expiration Date 59 - Fraud Risk 96 - Issuer Internal System Error
requestSource	The provisioning request source.
tokenRequestorId	The unique identifier of the token request initator.
orangeFlowIndicator	Identifies if a given authorisation request is flagged as high fraud risk by Apple (Orange Flow). Based on the 9th character of the `wallet_reasons` attribute.

Event Code 107 - Activation Code Notification (ACN)

The 107 event code is used to send out an Activation Code Notification (ACN).

{  
  "productId": 12345,
  "events": [107],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when an ACN has been made, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 107,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"publicToken": "123456789",
"productId": "124",
"paymentToken": "987654321",
"dpan": "5168563000002547",
"networkTokenReference": "67024958022",
"provisioningTraceId": "VIS1-20210318-381077544887139",
"tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
"processorDateTime": "2024-10-29T15:16:50Z",
"otpValue": "123456",
"otpReason": "TOKEN_DEVICE_BINDING",
"otpExpirationDate": "2024-10-29T15:46:30Z",
"activationMethod": "6",
"deviceInfo": {
		"deviceId": "01234B234C1230011230054848300695D86E17C703548A4A",
		"deviceType": "W"
							}
}
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
publicToken	The public token associated with the TAR notification.
productId	The unique identifier of the product.
paymentToken	Thredd's internal identifier for the payment token.
dpan	The DPAN identifier for the payment token.
networkTokenReference	The unique token reference from the network.
provisioningTraceId	The lifecycle identifier to link tokenisation events that are related.
tokenisationServiceDateTime	The event generation timestamp from the tokenisation service.
processorDateTime	The event processing timestamp from Thredd.
otpValue	The One-Time Passcode (OTP) value.
otpReason	The reason for the one One-Time Passcode (OTP). For example, `PAYMENT`, `TOKEN_DEVICE_BINDING`, `CARDHOLDER_STEPUP`, `RUSTED_LISTING_ENROLLMENT`.
otpExpirationDate	The OTP expiration timestamp.
activationMethod	The customer's activation method preference.
deviceInfo	Object that contains information on the device.
deviceId	The device ID for the tokenisation request.
deviceType	The device type for the tokenisation request.

Event Code 108 - Tokenisation Complete Notification (TCN)

The 108 event code is used to send out a Tokenisation Complete Notification (TCN).

{ 
  "productId": 12345,
  "events": [108],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when an TCN has been made, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 108,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z"
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
publicToken	The public token associated with the TAR notification.
productId	The unique identifier of the product.
paymentToken	Thredd's internal identifier for the payment token.
dpan	The DPAN identifier for the payment token.
networkTokenReference	The unique token reference from the network.
provisioningTraceId	The lifecycle identifier to link tokenisation events that are related.
tokenisationServiceDateTime	The event generation timestamp from the tokenisation service.
processorDateTime	The event processing timestamp from Thredd.

Event Code 109 - Tokenisation Event Notification (TEN)

The 109 event code is used to send out a Tokenisation Event Notification (TEN).

{ 
  "productId": 12345,
  "events": [109],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a TEN has been made, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 109,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z",
    "eventReason": "8",
    "messageReasonCode": "02",
    "eventRequestor": " ",
    "processorTokenStatus": "ACTIVE",
    "tokenisationServiceTokenStatus": "ACTIVE"
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
publicToken	The public token associated with the TAR notification.
productId	The unique identifier of the product.
paymentToken	Thredd's internal identifier for the payment token.
dpan	The DPAN identifier for the payment token.
networkTokenReference	The unique token reference from the network.
provisioningTraceId	The lifecycle identifier to link tokenisation events that are related.
tokenisationServiceDateTime	The event generation timestamp from the tokenisation service.
processorDateTime	The event processing timestamp from Thredd.
eventReason	The tokenisation event reason to indicate the reason why the event was triggered.
messageReasonCode	The reason code associated with a given event reason where applicable.
eventRequestor	Indicates the entity that requested the event.
processorTokenStatus	The issuer processor (Thredd) token internal status.
tokenisationServiceTokenStatus	The Tokenisation Service token status (For example, VDEP or MDES).

Event Code 110 - Tokenisation Status Update Failure Notification (TFN)

The 110 event code is used to send out a Failed Token Status Change notification.

{
  "productId": 12345,
  "events": [110],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a TFN has been made, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 110,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z",
    "processorTokenStatus": "ACTIVE",
    "tokenisationServiceTokenStatus": "ACTIVE"
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 104.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
publicToken	The public token associated with the TAR notification.
productId	The unique identifier of the product.
paymentToken	Thredd's internal identifier for the payment token.
dpan	The DPAN identifier for the payment token.
networkTokenReference	The unique token reference from the network.
provisioningTraceId	The lifecycle identifier to link tokenisation events that are related.
tokenisationServiceDateTime	The event generation timestamp from the tokenisation service.
processorDateTime	The event processing timestamp from Thredd.
processorTokenStatus	The issuer processor (Thredd) token internal status.
tokenisationServiceTokenStatus	The Tokenisation Service token status (for example, VDEP or MDES).

Event Code 111 - Apata finalised event

The 111 event code is used when Apata sends a finalised event.

{
  "productId": 12345,
  "events": [111],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when Apata sends a finalised event, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 111,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "version": "V2.0",
    "eventType": "FINALISED_EVENT",
    "transaction": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "dsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
      "threeDsServerTransactionId": "3f9430da-4dd7-473c-b3a3-5100a79deb0d",
      "cardProgramId": "ec737f30-0c61-4383-9732-83d7c7b38b49",
      "riskProfileId": "c0ca8866-27de-4ac6-bdda-8dfc24a74ae9",
      "challengePreference": "NO_PREFERENCE",
      "decoupledPreference": "REQUIRED",
      "amount": 1000,
      "currency": "EUR",
      "recurFrequency": 0,
      "recurEndDate": "2019-08-24",
      "installments": 0,
      "merchantId": "string",
      "merchantName": "string",
      "merchantCountry": "IRL",
      "mcc": "1234",
      "threeDsRequestorId": "string",
      "threeDsRequestorName": "string",
      "threeDsRequestorUrl": "string",
      "threeDsServerReferenceNumber": "string",
      "threeDsServerOperatorId": "string",
      "renderType": "APP_NATIVE",
      "date": "2019-08-24T14:15:22Z",
      "acquirerBin": "123456",
      "authenticationValue": "AABBCCDDEEFFAABBCCDDEEFFAAA=",
      "eci": "string",
      "state": "SUCCEEDED",
      "errorCode": "resource_not_found",
      "reason": "CARD_EXPIRED",
      "exemption": "LOW_VALUE_PAYMENT",
      "protocolVersion": "1.0.2",
      "category": "PAYMENT",
      "transactionType": "PAYMENT",
      "channel": "APP",
      "deviceIP": "string",
      "devicePlatform": "string",
      "deviceModel": "string",
      "deviceOs": "string",
      "deviceOsVersion": "string",
      "deviceLocale": "string",
      "deviceTimezone": "string",
      "deviceAdvertisingId": "string",
      "deviceScreenHeight": 0,
      "deviceScreenWidth": 0,
      "deviceName": "string",
      "deviceLatitude": 0,
      "deviceLongitude": 0,
      "deviceCountry": "string",
      "deviceLanguage": "string",
      "browserAcceptHeader": "string",
      "browserJavaEnabled": true,
      "browserJavascriptEnabled": true,
      "browserColourDepth": 0,
      "browserUtcOffsetMinutes": 0,
      "browserUserAgent": "string"
    },
    "challenges": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "challengeProfileId": "950c886e-8eba-4465-8443-d22f90d269f8",
        "challengeMethodId": "12b5985b-8771-477a-9d02-4528a83cf2b4",
        "challengeMethodAlias": "string",
        "challengeMethodType": "SMS_OTP",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z",
        "ttl": 300,
        "state": "PENDING"
      }
    ],
    "card": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "externalId": "my-custom-card-reference",
      "language": "en",
      "scheme": "VISA",
      "tags": {
        "property1": "string",
        "property2": "string"
      }
    }
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 111.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
version	The version of the event (for example, `V2.0`).
eventType	The type of the event, indicating this is a finalized event.
transaction	Object that contains details of the finalized transaction.
id	The unique identifier for the transaction.
dsTransactionId	The transaction ID assigned by the directory server.
threeDsServerTransactionId	The transaction ID assigned by the 3D Secure server.
cardProgramId	The ID representing the card program used for this transaction.
riskProfileId	The risk profile ID associated with the transaction.
challengePreference	The preference for challenges. For example, `CHALLENGE_MANDATED`.
decoupledPreference	The merchant’s preference for decoupled authentication.
amount	The purchase amount in the currency's minor unit.
currency	The ISO-4217 alpha currency code.
recurFrequency	The minimum number of days between authorisations.
recurEndDate	The date after which no further authorisations should be performed in the format.
installments	The max number of permitted instalment payments.
merchantId	The acquirer-assigned merchant identifier.
merchantName	The merchant name assigned by the Acquirer or Payment System.
merchantCountry	The ISO 3166 alpha country code for the merchant.
mcc	The directory server specific code describing the merchant's type of business, product or service.
threeDsRequestorId	The 3DS requestor ID.
threeDsRequestorName	The name of the 3DS requestor.
threeDsRequestorUrl	The URL of the 3DS requestor.
threeDsServerReferenceNumber	The reference number from the 3DS server.
threeDsServerOperatorId	The operator ID from the 3DS server.
renderType	The format in which the challenge is displayed to the cardholder.
date	The date the transaction was initiated.
acquirerBin	The BIN of the acquirer.
authenticationValue	The authentication value generated for the transaction.
eci	The Electronic Commerce Indicator representing the outcome of authentication.
state	The final status of the transaction.
errorCode	The error code provided for transactions that encountered an error.
reason	The explanation for why the transaction failed or was rejected.
exemption	For frictionless transactions, indicates the exemption type applied.
protocolVersion	The 3DS protocol version.
category	The classification of the transaction (For example, payment, non-payment).
transactionType	The type of transaction being processed.
channel	The channel through which the transaction originated (For example, browser, app).
deviceIP	The IP address of the device used for the transaction.
devicePlatform	The platform of the device used.
deviceModel	The model of the device used for the transaction.
deviceOs	The operating system of the device used.
deviceOsVersion	The operating system version of the device.
deviceLocale	The locale of the device.
deviceTimezone	The timezone of the device.
deviceAdvertisingId	The advertising ID of the device.
deviceScreenHeight	The screen height of the device.
deviceScreenWidth	The screen width of the device.
deviceName	The name of the device.
deviceLatitude	The latitude of the device’s location.
deviceLongitude	The longitude of the device’s location.
deviceCountry	The country of the device user.
deviceLanguage	The language of the device.
browserAcceptHeader	The value of the HTTP Accept header sent by the browser.
browserJavaEnabled	Indicates whether Java is enabled in the browser.
browserJavascriptEnabled	Indicates whether JavaScript is enabled in the browser.
browserColourDepth	The colour depth of the browser.
browserUtcOffsetMinutes	UTC offset in minutes of the browser.
browserUserAgent	The User Agent string of the browser.
transaction	End of the transaction object.
challenges	Object that contains details on the challenges performed if the transaction underwent a challenge.
id	The unique identifier of the challenge.
challengeProfileId	The identifier of the challenge profile in which this challenge method is configured.
challengeMethodId	The identifier of the challenge method used for this challenge.
challengeMethodAlias	The alias of the challenge method used for this challenge.
challengeMethodType	The type of the challenge method used.
created	When the challenge was created.
updated	When the challenge state was last updated.
ttl	The time limit (in seconds) set for completing this challenge.
state	The final status of the challenge.
challenges	End of the challenges object.
card	Object that contains information on the card.
id	The unique identifier of the card generated by Apata.
externalId	The unique identifier of the card generated by the issuer.
language	The ISO 639-1 or BCP-47 language code for the card.
scheme	The payment scheme of the card. For example, `MASTERCARD`.
tags	Object that contains custom tags associated with the card.
property1
property2
tags	End of the tags object.
card	End of the card object.
payload	End of the tags object.

Event Code 112 - Transaction Confirmation Event

The Transaction Confirmation (TC) events are a notification sent using Thredd's webhook service for transaction confirmations (Event Code = 112).

{
  "productId": 12345,
  "events": [112],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, you will start to receive TC events based on the configuration of your webhook and a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 112,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"network": "Visa",
"subnetwork": "STAR",
"programManagerCode": "FTX",
"programManagerName": "FintechX",
"programManagerResponse": "00",
"actualBalance": "1500.0000",
"additionalAmount": "50.0000",
"transactionFee": "2.00",
"processorAuthorisationCode": "134822",
"acquiringInstitutionId": "06003758",
"acquirerForwarderId": "000405700",
"availableBalance": "1480.0000",
"billingAmount": "100.0000",
"billingCurrency": "840",
"blockedAmount": "0.0000",
"customerAccount": "CUST123456",
"fxPadding": "1.25",
"fixedFee": "0.0000",
"rateFee": "0.0000",
"mcc": "5411",
"mccDescription": "Grocery Stores",
"mccPadding": "0.50",
"merchantId": "MID98765",
"merchantName": "Walmart NY",
"transactionNote": "Weekly grocery purchase",
"localTransactionTime": "010107",
"localTransactionDate": "20250626",
"processingCode": "000000",
"schemeResponseCode": "00",
"token": "123456789",
"transactionAmount": "100.0000",
"transactionCurrency": "840",
"acceptorCountryCode": "USA",
"transactionDescription": "POS Purchase",
"processorTransactionDateTime": "2025-05-28T10:15:17Z",
"transactionId": "789456123",
"transactionStatusCode": "A",
"transactionType": "A",
"isThreddAuthorised": "Y",
"avsResult": "Y",
"mtid": "0100",
"productId": "1234",
"velocityGroup": "VG01",
"posCapability": "0001000000000100000000000000000000100000000230000",
"posData": "58V9000900000Px100",
"transactionLifeCycleId": "VIS1-20160608-086160508692217",
"transLink": "250415787144555555",
"retrievalReferenceNumber": "510559697285",
"posTerminal": "ECOMM001",
"networkFraudData": "",
"paymentTokenId": "998877",
"paymentTokenWallet": "APPLE"
}
}

The below table describes each of the fields included in the notification response.

Field	Description	Type	Mandatory
context	The context object.
notificationId	Unique identifier of the notification.	String	Yes
eventCode	The event code of the event.	Integer	Yes
eventVersion	The version of the event.	String	Yes
notificationTime	Notification created time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.	String	Yes
payload	The payload object.
network	Primary card network (Visa, Mastercard, DGN).	String	Yes
subnetwork	Merchant routing network (STAR, Pulse, DGN), Value only present for MNE transactions.	String	No
programManagerCode	The Program Manager code.	String	Yes
programManagerName	The Program Manager name.	String	No
programManagerResponse	The Program Manager response. Empty for EHI mode 3 transactions, Thredd generated transactions and non-EHI transactions.	String	No
actualBalance	Actual balance after transaction (in the card account currency).	String	No
additionalAmount	The additional amount (DE54).	String	No
transactionFee	The transaction fee (DE28).	String	No
processorAuthorisationCode	Authorisation code generated by Thredd for approved and declined authorisation requests.	String	No
acquiringInstitutionId	The Acquiring Bank ID as assigned by the network.	String	No
acquirerForwarderId	Identifies the acquiring institution forwarding a Request or Advice message.	String	No
availableBalance	Available balance after transaction.	String	No
billingAmount	Settlement billing amount.	String	No
billingCurrency	Billing currency (ISO 3-digit numeric).	String	No
blockedAmount	Blocked amount after transaction.	String	No
customerAccount	The customer account reference.	String	No
fxPadding	Foreign currency padding.	String	No
fixedFee	Total fixed fee amount.	String	No
rateFee	Total percentage rate fee amount.	String	No
mcc	Merchant Category Code. 4-digit MCC.	String	No
mccDescription	MCC description.	String	No
mccPadding	MCC padding.	String	No
merchantId	Merchant ID.	String	No
merchantName	Merchant name and location.	String	No
transactionNote	Note about the transaction.	String	No
localTransactionTime	Local merchant transaction time.	String	No
localTransactionDate	Terminal local date of transaction. MMDD with YYYY added by Thredd. YYYY='0000' if MMDD invalid.	String	No
processingCode	Processing code for transaction.	String	No
schemeResponseCode	Scheme response code (For example, "00" or "05").	String	No
token	Thredd public token of card.	String	Yes
transactionAmount	The transaction amount.	String	Yes
transactionCurrency	Transaction currency (ISO 3-digit). For example, "840".	String	Yes
acceptorCountryCode	Transaction country (ISO 3-alpha). For example, "USA".	String	No
transactionDescription	Description of the transaction.	String	No
processorTransactionDateTime	Date and time of processing. Format: yyyy-MM-ddTHH:mm:ssZ	String	No
transactionId	Unique transaction ID.	String	Yes
transactionStatusCode	Transaction status code.	String	No
transactionType	The transaction type.	String	Yes
isThreddAuthorised	Indicates if the transaction is authorised by Thredd. "Y" or "N".	String	No
avsResult	The Address Verification System (AVS) result.	String	No
mtid	The Message Type Identifier. For example, "0100" or "0400".	String	No
productId	The Product ID of the card.	String	Yes
velocityGroup	Velocity group code.	String	No
posCapability	POS capability codes.	String	No
posData	POS data codes.	String	No
transactionLifeCycleId	Lifecycle Trace ID.	String	Yes
transLink	Identifier to link related transactions.	String	No
retrievalReferenceNumber	Retrieval Reference Number.	String	No
posTerminal	POS Terminal ID.	String	No
networkFraudData	Fraud or Risk Indicators received from the card network. For example, Visa: '011099 1122 013099 33'	String	No
paymentTokenId	Payment token ID.	String	No
paymentTokenWallet	Wallet the payment token belongs to. For example, APPLE (For Apple Pay Wallet) or SAMSUNG (For Samsung Pay Wallet).	String	No

Event Code 115 - FTM Alert Creation

📘
Note
To use this event code, you must be onboarded for Fraud Transaction Monitoring, and have valid fraud rules set up. For more information, speak to your Account Manager.

The 115 event code is used when a new alert is created in Fraud Transaction Monitoring (FTM).

{
  "productId": 12345,
  "events": [115],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when an alert is created in FTM, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 115,
    "eventVersion": "v1",
    "notificationTime": "2025-10-29T23:20:28Z"
  },
  "payload": {
    "AlertTime": "2025-10-29T15:00:00Z",
    "EventTime": "2025-10-29T14:59:30Z",
    "AlertId": "1814885-SleFPH53",
    "EventId": "46d99b92-0d4d-48a4-97a4-eba49b94c9f1",
    "EventType": "cardRT",
    "SystemEventId": "1814885-SleFPH53",
    "ThreddTransactionId": "6167181535",
    "CustomerId": "TRD-1",
    "CardId": "3181200146334628",
    "ProductId": "10030",
    "ProgramManagerCode": [
      "TRD"
    ],
    "TenantId": [
      "TRD"
    ],
    "ActionTags": [
      {
        "Tag": "Action",
        "Values": [
          "Decline"
        ]
      }
    ],
    "TriggeredRules": [
      "AlertingRule",
      "AlertingRule_2"
    ],
    "TriggeringEntities": [
      "3181200136754628",
      "TRD-1"
    ]
  }
}

The below table describes each of the fields included in the notification response.

Field	Description
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.
eventCode	The event code. In this case, the event code is 115.
eventVersion	The event version.
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.
payload	Object that contains the payload of the notification, which is specific to the event code.
AlertTime	The time the alert was generated. This can be null if not applicable.
EventTime	The time the event occurred that triggered the alert.
AlertId	The unique identifier for the alert.
EventId	The unique identifier for the event.
EventType	The event type that triggered the alert.
SystemEventId	The FTM generated identifier for the event.
ThreddTransactionId	The identifier for the Thredd transaction associated with the event.
CustomerId	The identifier for the customer involved in the event.
CardId	The identifier for the card involved in the event.
ProductId	The identifier for the product associated with the card or transaction.
ProgramManagerCode	The list of program manager codes associated with the event.
TenantId	The list of tenant identifiers associated with the event.
ActionTags	Object that contains representing actions taken, aggregated from all entities.
Tag	The name of the tag, indicating the type of action or metadata.
Values	Array of values associated with the tag.
ActionTags	End of the ActionTags object.
TriggeredRules	The list of rules that were triggered by the event.
TriggeringEntities	The list of entities that triggered the alert.

Event Code 117 - Open Banking Registration

The 117 event code is used when a customer interacts with an Open Banking registration session.

{
  "productId": 12345,
  "events": [117],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when a customer interacts with the application, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. The payload reflects what the customer is doing when they register, and can be one of the following event types:

started is sent when the Data Connect application is loaded and the landing web page is displayed.
institutionSupported is sent when a user selects a financial institution from a search query that is certified for the product.
discovered is sent after the customer has successfully signed in to an institution.
adding is sent when a customer enters their sign-in information at a financial institution and selects which accounts Data Connect can access to verify their financial information.
added is sent after the customer loads an eligible accounts page, and selects the account(s) they want to give access to. The accounts are saved in the resource for the account associated with the customer.
done is sent after the customer completes all necessary data connection requirements for the experience and the session ends. This event type follows the added event type.
institutionNotFound is sent when the user searches for an institution that is not recognised by Mastercard.
institutionNotSupported is sent when the user selects an institution that isn’t certified.
unableToConnect is sent when a financial institution is unavailable (unknown reasons) and a connection isn’t possible.
invalidCredentials is sent when the user enters incorrect sign-in information for the selected institution when using a legacy connection.

See the below examples of the different responses.

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-10T10:30:42.149118Z"
    },
    "payload": {
        "event_type": "adding",
        "event_id": "1660148602272-c7cb9456479bdce2befc3424",
        "payload": {
            "institutionId": "101732",
            "oauth": "true"
        },
        "webhook_data": {
            "threddSessionId": "34fe98c9-da7a-47c6-893c-b77e7f070f20"
        },
        "event_trigger": null,
        "openbanking_customer_id": "b1b915a3-800c-42bf-87b6-64d7ff3b63f2"
    },
    "messageHeaders": {
        "schemaId": 1
    }
}

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-10T10:27:14.094918Z"
    },
    "payload": {
        "event_type": "institutionNotSupported",
        "event_id": "1660148602272-c7cb9456479bdce2befc3424",
        "payload": {
            "institutionId": "101732"
        },
        "webhook_data": {
            "threddSessionId": "603afe05-1a92-4657-b5c7-03cf36d9dfe6"
        },
        "event_trigger": null,
        "openbanking_customer_id": "b1b915a3-800c-42bf-87b6-64d7ff3b63f2"
    },
    "messageHeaders": {
        "schemaId": 1
    }
}

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-09T13:52:44.821671Z"
    },
    "payload": {
        "event_type": "discovered",
        "event_id": "1770645163017-e4a16a9a3b1a8697b9959fac",
        "payload": {
            "accounts": [
                {
                    "id": 9011352680,
                    "number": "xxxxxx8888",
                    "name": "Auto Loan",
                    "balance": -209.52,
                    "type": "loan",
                    "status": "pending",
                    "institutionLoginId": 9005851697
                },
                {
                    "id": 9011352687,
                    "number": "xxxxxx1111",
                    "name": "Checking",
                    "balance": 209.52,
                    "type": "checking",
                    "status": "active",
                    "institutionLoginId": 9005851697
                }
            ],
            "mfa": null,
            "institutionId": "101732",
            "oauth": false
        },
        "webhook_data": {
            "threddSessionId": "34fe98c9-da7a-47c6-893c-b77e7f070f20"
        },
        "event_trigger": null,
        "openbanking_customer_id": "4c04d862-d3cb-4a4d-a9b8-0af31a8bd9d8"
    },
    "messageHeaders": {
        "schemaId": 1
    }
}

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-09T13:52:49.363973Z"
    },
    "payload": {
        "event_type": "added",
        "event_id": "1770645167089-ef46b3bebce351d0c9c6f176",
        "payload": {
            "accounts": [
                {
                    "id": "9011352680",
                    "number": "xxxxxx8888",
                    "accountNumberDisplay": "8888",
                    "name": "Auto Loan",
                    "balance": -209.52,
                    "type": "loan",
                    "status": "active",
                    "institutionId": "101732",
                    "balanceDate": 1770645163,
                    "aggregationAttemptDate": 1770645163,
                    "createdDate": 1770110113,
                    "lastUpdatedDate": 1770645167,
                    "linkedAccountDate": 1770645167,
                    "currency": "USD",
                    "institutionLoginId": 9005851697,
                    "displayPosition": 1,
                    "financialinstitutionAccountStatus": "OPEN",
                    "accountNickname": "Auto Loan",
                    "marketSegment": "personal"
                }
            ],
            "institutionId": "101732",
            "oauth": false
        },
        "webhook_data": {
            "threddSessionId": "34fe98c9-da7a-47c6-893c-b77e7f070f20"
        },
        "event_trigger": null,
        "openbanking_customer_id": "4c04d862-d3cb-4a4d-a9b8-0af31a8bd9d8"
    },
    "messageHeaders": {
        "schemaId": 1
    }
}