# Consent Notifications Structure source: https://developer.mastercard.com/open-finance-au/documentation/consent/consent-notifications-structure/index.md All Consent Notification events have the same structure, containing three parts: * A set of fields that identify a consent notification event. * A description of what happened to the consent that triggered the event. * The consent as it is at the moment after the change occurred. ```json { "{{fields identifying a consent notification event}}" "payload": { "changes": { "summary": "{{a verbal explanation of the change that happened to the consent at the moment of the event}}", "details": "{{a list of the changes that happened to consent per arrangement with an institution}}" }, "consent": { "{{all details of the consent as they are at the moment after the change occurred}}" } } } ``` For example: ```json { "eventId": "ac7e616b-8bf1-43a9-9ed4-11d9da2550c8", "eventType": "INSTITUTIONS_REVOKED", "eventContext": "CONSENT", "eventTime": "2023-05-28T10:43:52Z", "customerId": "1005061234", "payload": { "changes": { "errorCode": null, "summary": "One or more consent arrangements with Data Holder institutions have been revoked", "details": [ { "consentReceiptId": "123e4567-e89b-42d3-a456-556642440000", "institutionId": "4222", "institutionLoginId": "1007302745", "accountIds": [ "1014136057", "1014136058" ] } ] }, "consent": { "consentReceiptId": "123e4567-e89b-42d3-a456-556642440000", "customerId": "1005061234", "purpose": "Verify Balance", "purposeStatement": "to verify your current account balance", "statusDetails": { "status": "ACTIVE", "statusDate": "2023-05-28T10:43:52Z" }, "allowedTrnxHistorySinceDate": "2022-03-10T06:06:20Z", "allowedTrnxHistoryInDays": 365, "createdDate": "2023-03-10T06:06:20Z", "institutions": [ { "institutionId": "4222", "institutionLoginId": "1007302745", "institutionName": "Finbank", "oauthEnabled": true, "accounts": [ { "id": "1014136057", "status": "INACTIVE" }, { "id": "1014136058", "status": "INACTIVE" } ], "statusDetails": { "status": "REVOKED", "statusDate": "2023-05-28T10:43:52Z" }, "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" }, "createdDate": "2023-03-10T06:06:45Z", "lastUpdatedBy":"CUSTOMER" }, { "institutionId": "4237", "institutionLoginId": "1007302749", "institutionName": "Bank of Australia", "oauthEnabled": true, "accounts": [ { "id": "3034177095", "status": "ACTIVE" }, { "id": "3034177096", "status": "ACTIVE" } ], "statusDetails": { "status": "ACTIVE", "statusDate": "2023-03-10T06:07:31Z" }, "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" }, "createdDate": "2023-03-10T06:07:31Z", "lastUpdatedBy":"CUSTOMER" } ], "dataScopes": [ { "id": "bank:accounts.basic:read", "name": "Account name, type, and balance", "details": [ "Name of account", "Type of account", "Account balance" ] }, { "id": "bank:accounts.details:read", "name": "Account numbers and features", "details": [ "Account number", "Interest rates", "Fees", "Discounts", "Account terms", "Account mail address" ] } ], "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" } } } } ``` #### Event identifying fields {#event-identifying-fields} Example: ```json { "eventId": "ac7e616b-8bf1-43a9-9ed4-11d9da2550c8", "eventType": "INSTITUTIONS_REVOKED", "notificationType": "CONSENT", "eventTime": "2023-05-28T10:43:52Z", "customerId": "1005061234", "payload": { ... } } ``` | Field | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `eventId` | A webhook notification event unique number. | | `eventType` | A webhook notification event type. Possible values are: * `CONSENT_CREATED` --- This event is triggered when a customer initiates consent. At this point consent is in DRAFT state. Such consent does not have any institution added yet and is not usable for retrieving the customer's financial data yet. * `INSTITUTIONS_ADDED` --- This event is triggered whenever a customer successfully consents to share accounts for a specific Financial Institution. At this moment overall consent is ACTIVE and the data from the added accounts can be requested. * `INSTITUTIONS_AMENDED` --- Triggered when an existing institution arrangement is amended. This occurs when the customer re-authenticates to extend the consent duration or update account selections. After amendment, the arrangement remains *ACTIVE*, and updated account data can be accessed. * `INSTITUTIONS_NOT_ADDED` --- Triggered when an attempt to add or amend an institution fails or is canceled. This event signals that no changes were applied to the consent for the targeted institution. * `INSTITUTIONS_REVOKED` --- This event will triggered whenever a customer revokes arrangement to access accounts for particular institution(s). The revoked institutions become INACTIVE in consent and no more data can be requested from them. If there are no more active institutions left, then the overall consent becomes `INACTIVE` as well. * `INSTITUTIONS_EXPIRED` --- This event will be triggered whenever the arrangement to access the accounts of the specific institution(s) expires. The expired institutions become `INACTIVE` in consent and no more data can be requested from them. If there are no more active institutions left, then the overall consent becomes INACTIVE as well. Some of these event types indicate that further actions are required when the notification is received. Refer to [Processing Consent Notifications](https://developer.mastercard.com/open-finance-au/documentation/consent/processing-consent-notifications/index.md) for more details. | | `eventContext` | Represents the context in which the event has happened. Possible values are: * `CONSENT` --- Notification specific to data sharing consent when there is a change in data sharing consent. * `CONNECT` --- Notification specific to Connect journey when customer interacts with the Connect application.
**NOTE:** Currently this structure refers only to Consent notifications. For information on how to receive the Connect events, refer to the [Connect Webhooks](https://developer.mastercard.com/open-finance-au/documentation/connect/webhooks/index.md). | | `eventTime` | A date and time when the event notification was created. The field value is in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `customerId` | A Mastercard Open Finance customer ID. See also [Customers](https://developer.mastercard.com/open-finance-au/documentation/access-and-config/customers/index.md). | #### Details of the consent changes {#details-of-the-consent-changes} Example: ```json { ... "payload": { "changes": { "summary": "One or more consent arrangements with Data Holder institutions have been revoked", "details": [ { "consentReceiptId": "123e4567-e89b-42d3-a456-556642440000", "institutionId": "4222", "institutionLoginId": "1007302745", "accountIds": [ "1014136057", "1014136058" ] } ] }, "consent": { ... } } } ``` | Field | Description | |-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `changes` | Changes that actually happened to the consent at the point of time that triggered the event. | | `* summary` | Text explanation of the change that happened to the consent at the moment of the event. | | `* details` | A list of the changes to the consent. | | `** consentReceiptId` | A unique identifier of the consent given for a particular purpose. | | `** institutionId` | A Mastercard institution ID of an institution under consent affected by the change that triggered the event: * For the `CONSENT_CREATED` event, this value is empty as no institution has been added to the consent yet. * For all other event types, this value has an id of institution added, revoked or expired under the consent accordingly. | | `** institutionLoginId` | A Mastercard institution login ID (from the account record), represents a unique identifier for the authentication with the institution used to obtain consent: * For the `CONSENT_CREATED` event, this value is empty as no institution has been added to the consent yet. * For all other event types, this value has a login id of the institution added, revoked or expired under the consent accordingly. | | `** accountIds` | A list of Mastercard Open Finance account IDs for each account consented under the institution affected by the changes to consent. * For the `CONSENT_CREATED` event, this value is empty as no institution has being added to the consent yet. * For the `INSTITUTIONS_ADDED` event, this value has a list of accounts that a customer gave consent to access. * For all other event types, this value has a list of previously consented accounts to access which has been revoked or expired accordingly. | #### Consent {#consent} Example: ```json { ... "consent": { "consentReceiptId": "123e4567-e89b-42d3-a456-556642440000", "customerId": "1005061234", "purpose": "Verify Balance", "purposeStatement": "to verify your current account balance", "statusDetails": { "status": "ACTIVE", "statusDate": "2023-05-28T10:43:52Z" }, "allowedTrnxHistorySinceDate": "2022-03-10T06:06:20Z", "allowedTrnxHistoryInDays": 365, "createdDate": "2023-03-10T06:06:20Z", "institutions": [ { "institutionId": "4222", "institutionLoginId": "1007302745", "institutionName": "Finbank", "oauthEnabled": true, "accounts": [ { "id": "1014136057", "status": "INACTIVE" }, { "id": "1014136058", "status": "INACTIVE" } ], "statusDetails": { "status": "REVOKED", "statusDate": "2023-05-28T10:43:52Z" }, "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" }, "createdDate": "2023-03-10T06:06:45Z", "lastUpdatedBy":"CUSTOMER" }, { "institutionId": "4237", "institutionLoginId": "1007302749", "institutionName": "Bank of Australia", "oauthEnabled": true, "accounts": [ { "id": "3034177095", "status": "ACTIVE" }, { "id": "3034177096", "status": "ACTIVE" } ], "statusDetails": { "status": "ACTIVE", "statusDate": "2023-03-10T06:07:31Z" }, "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" }, "createdDate": "2023-03-10T06:07:31Z", "lastUpdatedBy":"CUSTOMER" } ], "dataScopes": [ { "id": "bank:accounts.basic:read", "name": "Account name, type, and balance", "details": [ "Name of account", "Type of account", "Account balance" ] }, { "id": "bank:accounts.details:read", "name": "Account numbers and features", "details": [ "Account number", "Interest rates", "Fees", "Discounts", "Account terms", "Account mail address" ] } ], "accessPeriod": { "startDate": "2023-03-10T06:06:20Z", "endDate": "2023-07-09T06:06:20Z" } } } } ``` | Field | Description | |-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `consentReceiptId` | A unique identifier of the consent given for a particular purpose. | | `customerId` | A Mastercard Open Finance customer ID. See also [Customers](https://developer.mastercard.com/open-finance-au/documentation/access-and-config/customers/index.md). | | `purpose` | A reason a customer needs to give access to their financial information and reflects the service that will be provided to the customer using this consent. For example, the purpose can be "Verify Balance". Other example values include: * "Manage Your Budget" * "Account Opening" * "Funds Transfer" * "Home Loan Origination" * "Business Loan Origination" * "Credit Card Application" * "Review Credit Limit" * "Debt Consolidation Loan" * "Verify Account Details \& Ownership" * "Verify Balance" * "Personal Loan" * "Payment" If you need a customised value, contact your Mastercard representative. | | `purposeStatement` | A customer-friendly explanation what the consent will be used for and is based on the purpose. For example for purpose "Verify Balance" the purposeStatement is "to verify your current account balance". This information is displayed to the customers in the consent agreement and consent receipt. Example values include: * "to manage your budget" * "to open an account" * "to verify payment information" * "to support your home loan application" * "to support your business loan application" * "to support your credit card application" * "to verify your credit limit" * "to support your debt consolidation application" * "to verify account details and ownership" * "to verify your current account balance" * "to support your personal loan application" * "to support your money transfer" If you need a customised value, contact your Mastercard representative. | | `statusDetails` | Details on the current status of the consent. | | `* status` | Current status of the consent. Possible values are: * `DRAFT` - Consent receipt created without any institution details. * `ACTIVE` - One of the institution arrangements under the consent is `ACTIVE`. Customer's data can be accessed using this consent. * `INACTIVE` - None of the institution arrangements under the consent is `ACTIVE`. Customer's data can not be accessed further using this consent. | | `* statusDate` | Date and time when the consent was updated. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `allowedTrnxHistoryInDays` | Number of days into the past to which the consent allows to access transactions. For example, if this value is set to 60, then the consent allows to access the transactions from the last 60 days from the start time of the consent agreement. If the value is 0 (zero), it means the consent does not allow accessing the transactions that happened prior the starting date of the consent. The maximum allowed value is 365. | | `allowedTrnxHistorySinceDate` | Date and time in the past from which consent allows to access the past transactions. For example, if the date represents the 2nd of Feb 2020, the consent allows accessing only of the transactions not older than the 2nd of Feb 2020. This information is displayed to the customers in the consent agreement and consent receipt. If the allowedTrnxHistoryInDays value is 0 meaning the access to the transactions in the past is not allowed, then this allowedTrnxHistorySinceDate field will contain null. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `createdDate` | Date and time when the consent was created. The date counts from the moment the Draft version of the consent was created even before the first institution arrangement is added to it. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `institutions` | An array of institution arrangements added to this consent. | | `* institutionId` | A Mastercard Open Finance ID of a Financial Institution. | | `* institutionLoginId` | An institution login ID, represents a unique identifier for the authentication with the institution to obtain consent agreement. | | `* institutionName*` | A name of the institution. | | `* oauthEnabled` | `true`: The institution is an OAuth connection | | `* accounts` | An array of the accounts to which a customer granted access within current consent agreement. The information about which accounts are accessed is shown to the customer in the consent agreement. | | `** id` | A Mastercard Open Finance account ID. | | `** status` | Status of account in consent agreement. Possible values are: * `ACTIVE` - Account data can be accessed. * `INACTIVE` - Account data cannot be accessed further. * `PENDING` - Account data cannot be accessed yet. | | `* statusDetails` | Details on the current status of the arrangement with the institution. | | `** status` | Current status of arrangement with the institution. Possible values are: * `ACTIVE` - Accounts data of an institution can be accessed. * `REVOKED` - Arrangement with the institution is revoked. Accounts data of an institution can not be accessed anymore. * `EXPIRED` - Arrangement with the institution is expired. Accounts data of an institution cannot be accessed anymore. | | `* accessPeriod` | A period of time allowed for accessing the customer's data granted by the arrangement with this particular institution. This information is displayed to the customers in the consent agreement and consent receipt. | | `** startDate` | Date and time from which the customer's data can be accessed. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `** endDate` | Date and time until the customer's data can be accessed. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `* createdDate` | Date and time when the arrangement with the institution was added to the consent. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `* lastUpdatedBy` | Represents who updated the status of the arrangement with the institution. Possible values are: * `CUSTOMER` - when the update is made by customer, e.g., arrangement is revoked. * `PARTNER` - when the update is made by a partner, e.g., an arrangement was revoked as result of a customer being deleted. * `INSTITUTION` - when the update is made by the institution, e.g., the arrangement is revoked by the institution on behalf of customer. * `SYSTEM` - when the update is made by the automated processes in the Mastercard Open Finance system, e.g., arrangement expires. * `INTERNAL` - when the update is made via internal Mastercard services, e.g., dispute resolution team revokes the consent on the customer's request. | | `dataScopes` | Scope of the customer's data that this consent allows to access. An array of the data scope object. | | `* id` | An id of the scope defined as per CDR regulation in Australia. | | `* name` | A customer-friendly name of the data scope. This information is to be displayed to the customers in the consent agreement. | | `* details` | A list of the types of customer's data in this particular scope that this consent allows to access. For example, * "Name" * "Occupation" * "Phone" * "Email address" * "Mail address" * "Residential address" This information is to be displayed to the customers in the consent agreement. | | `accessPeriod` | A period of time allowed for accessing the customer's data granted by this consent. If the consent contains more than one institution arrangement, then this period is defined by the longest one. This information is displayed to the customers in the consent agreement and consent receipt. | | `* startTime` | Date and time from which the customer's data can be accessed. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). | | `* endTime` | Date and time until the customer's data can be accessed. Date and time in ISO 8601 format. See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md). See also [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-au/documentation/support/index.md) |