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"
    }
  }
}

Response

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
    }
}

Microdeposit Response

If you have your experienceId enabled for microdeposits (fallback), then the payload for the 117 Event Code response includes details for the microdeposit account. The id included in the response is required to use the Create Microdeposit Verification Link endpoint.

📘
Note
To enable microdeposits, contact your Thredd Implementations Manager.

When the microdeposits fallback option has been enabled, additional screens are added in the Open Banking registration user journey where the customer enters their bank account details manually. This initiates two microdeposits.

The customer then needs to be prompted to check their banking app or website after the microdeposit is made, with a webhook response sent when the deposit is done. Note that microdeposits can take up to three days to settle and be visible in the customer's bank account.

📘
Note
When microdeposits are received and the 117 webhook event returns a microdepositCompleted event_type, the customer has ten days to return and enter the two microdeposit amounts to verify their bank account. The customer has three attempts to verify the microdeposits.

When the microdeposit has been verified you can generate a microdeposit verification using the Create Microdeposit Verification Link endpoint, which enables your customer to confirm the deposit amount in order to validate the banking information.

Event Type	Meaning
microdepositInitiated	Microdeposits submitted. This includes accountId, status, depositCount, railType.
microdepositPending	Microdeposits are in progress.
microdepositCompleted	The microdeposits are dispatched. The id in accounts object is the Mastercard account id used for the Create Microdeposit Verification Link endpoint URL.
microdepositVerified	The deposits are verified for user verified amounts and customer financial account details can be fetched.
microdepositRejected	The deposit is rejected.
microdepositReturned	The deposit is returned.
microdepositFailed	The deposit failed.
microdepositExpired	The verification window expired.
microdepositVerificationReminder	Reminder for the user to complete verification.
microdepositError	A deposit error.
microdepositVerificationError	A deposit verification error.

See the below examples of the different payloads of the response.

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-10T10:30:42.149118Z"
    },
    "payload": {
    "event_type": "microdepositInitiated",
    "mastercard_event_type": "microdepositInitiated",
    "event_id": "1778681139356-1a9db5af4c14672a8a1e6928",
    "payload": {
      "accountId": "9022047419",
      "status": "Pending",
      "depositCount": 2,
      "statusDescription": "Deposits are submitted for processing",
      "railType": "rtp"
    },
    "webhook_data": { "threddSessionId": "9f527de4-b233-4564-8492-3067b6cfa08b" },
    "openbanking_customer_id": "e0e9c57c-ba40-41d5-8cef-64bfcb6939aa"
  }
}

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-10T10:30:42.149118Z"
    },
    "payload": {
    "event_type": "microdepositCompleted",
    "mastercard_event_type": "microdepositStatus",
    "event_id": "1778681141560-5332c0cdf92c6f7643af78a8",
    "payload": {
      "event": { "type": "statusChange", "class": "microdeposit" },
      "accounts": [{
        "id": "9022047419",
        "name": "Savings",
        "type": "moneyTransferSavings",
        "microdepositStatus": "Completed",
        "description": "Microdeposits initiated successfully."
      }]
    },
    "webhook_data": { "threddSessionId": "9f527de4-b233-4564-8492-3067b6cfa08b" },
    "openbanking_customer_id": "e0e9c57c-ba40-41d5-8cef-64bfcb6939aa"
  }
}

{
    "context": {
        "programManagerId": 12345,
        "eventCode": 117,
        "eventVersion": "v1",
        "notificationTime": "2026-02-10T10:30:42.149118Z"
    },
    "payload": {
    "event_type": "microdepositVerified",
    "mastercard_event_type": "microdepositStatus",
    "event_id": "1778b81394222-e73fa66e6846962b845c3899",
    "payload": {
      "event": { "type": "statusChange", "class": "microdeposit" },
      "accounts": [{
        "id": "9022047419",
        "name": "Savings",
        "microdepositStatus": "Verified",
        "status": "active",
        "description": "Microdeposits verified successfully. ACH details are now available to fetch."
      }]
    },
    "openbanking_customer_id": "e0e9c57c-ba40-41d5-8cef-64bfcb6939aa"
  }
}