# Payment Risk Insights Report
source: https://developer.mastercard.com/open-finance-us/documentation/products/small-business/payment-history/index.md
## Overview {#overview}
The Payment Risk Insights report retrieves up to 24 months of transaction history from connected accounts, and calculates a risk score based on a business's financial history. The risk score can be used to determine the probability that a business will experience a payment risk event, such as Non-Sufficient Funds/Overdraft or missed recurring payments, in the near future when making a payment.
Note: Payment Risk Insights will soon be updated to support consumer use cases. The consumer report will follow the same structure as the Small Business report.
#### Key Product Features {#key-product-features}
* **Account Owner:** See the listed account owner name and address to assist in fraud reduction
* **Data History** : Up to 24 months of categorized transaction data based on availability from the FI(s). Length of history is customizable using the `fromDate` and defaults to 24 months
* **Payment Risk Insights Analytics:**
* Monthly average income over the previous 24 months
* Total deposit amount by month for all accounts and level of confidence that it represents income
* Total withdrawal amount by month for all accounts
* Number of NSF counts and aggregate amount per month
* Recurring loan payment amounts per month
* Insurance payment amount per month
* Tax payment amounts per month
* **Risk Score** representing the likelihood of a missed payment
* **Time Interval Type:** The periodicity at which attributes will be calculated. Available options range from Daily all the way to Historical (a report would include one set of attributes covering the entire history). Up to 2 time intervals may be requested per report. Defaults to Monthly Calendar
#### Additional Product Information {#additional-product-information}
* **Connected Accounts Summary:** Includes information such as the financial institution (FI) name, last four digits of the account number, account type, and balance **FI Certification Type** : Transaction Aggregation (TA). Each FI goes through a certification process to make sure the right data is consistently provided to make the product successful. See [the list of certified FIs](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/supported-institutions/index.md) for this product
* **Report Generation Time (median):** Less than 20 seconds
* **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshing a report is billable at a discounted rate.
* **Supported Account Types**: Checking, Savings
* **Supported Report Format:** JSON and PDF
#### **Use Cases** {#use-cases}
For partners working with small and medium businesses, there is a need
to understand the likelihood of missing a payment by the business owner.
The following list provides several use cases where the Payment Risk Insights
Report can be employed to simplify small and medium business financial
decisions.
* **Onboarding and Payments** - Lenders can incorporate Payment Risk Insights Report into their onboarding flow to immediately assess the risk of a potential customer and price this risk accordingly.
* **Business Financial Management** - Financial solutions providers can leverage the Payment Risk Insights Report to be able to provide insights to the small and medium sized businesses (SMBs) regarding their payment history.
* **Loan Issuance** - Lenders can use the Risk Score and additional attributes in the Payment Risk Insights Report when deciding whether to approve a small business for a business loan or business credit card.
* **Account Management** - Lenders can use Payment Risk Insights Report to make account management decisions such as credit limit adjustments and interest rate changes.
#### Sequence Diagram {#sequence-diagram}
Diagram payment-history-report
## How it Works {#how-it-works}
### Prerequisites {#prerequisites}
This product is dependent on the customer linking their bank accounts
via Mastercard Data Connect.
* [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) to call the API.
* [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token)
* [Create a customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers).
* [Create a consumer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers) record for business use cases where the applicant is personally guaranteeing the loan.
* [Create and link a business record to the customer](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#businesses).
* [Generate a connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) and [link customer accounts](https://developer.mastercard.com/open-finance-us/documentation/connect/index.md#the-data-connect-flow).
### Generate a Payment Risk Insights Report {#generate-a-payment-risk-insights-report}
To generate or refresh a Payment Risk Insights Report use the following
endpoint:
API Reference: `POST /decisioning/customers/{customerId}/reports/payment-history/userTypes/business`
The response includes the status of the report generation and a
report ID.
If you are using report webhooks (recommended),
a notification is sent to the webhook listener when report generation
is complete or an error occurs
(see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)).
If you are not using report webhooks, you can poll one of the
[Get Report endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md)
every 20 seconds until the report is returned.
#### Implementation Notes {#implementation-notes}
* Use the `fromDate` parameter to customize the transaction history included in the report. By default, 24 months of history will be aggregated as available.
* Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types.
* Use `timeIntervalType` to select the period at which attributes will be calculated. Defaults to Monthly Calendar.
* Customize the type of Payment Risk Insights report received based on inputs provided when generating the report:
| **Report Type** | **User Type/Experience** | **forCraPurpose** | **Applicant is Personal Guarantor** | **Consumer Required** | **Customer Required** | **Business Required** |
|-----------------|--------------------------|-------------------|-------------------------------------|-----------------------|-----------------------|-----------------------|
| phrbcra | business | true | true | true | true | true |
| phrbnoncra | business | false | false | false | true | true |
| phrbftc | business | true | false | false | true | true |
Note: The CRA version of the Payment Risk Insights Report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and you must provide a [permissible purpose](https://developer.mastercard.com/open-finance-us/documentation/products/lend/permissible-purpose-codes/index.md) code when retrieving the report. Provision and use of this report is subject to all applicable obligations of the FCRA.
## Get Payment Risk Insights Reports {#get-payment-risk-insights-reports}
Once the report is generated, retrieve the report using one of the [Get Report](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints.
## Example Reports {#example-reports}
The Get Report response contains different data depending on the
type of report requested. The following example shows what a successful
JSON response could look like for this report. Examples are meant for
reference only and may lag production changes.
```json
{
"id": "sd1j45yn37wr-phrbcra",
"customerType": "active",
"customerId": 1275320,
"requestId": "7a7qyps2iy",
"requesterName": "Decisioning API",
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "1-801-443-7288",
"email": "customerservice@example.com",
"url": "example.com"
},
"title": "Mastercard Open Banking Payment History Analytics",
"consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4",
"consumerSsn": "1234",
"disputeStatement": "Invalid data present.",
"businessDetails": {
"id": 123,
"name": "Name1",
"address": {
"addressLine1": "2020 State Street",
"addressLine2": "Suite 301",
"city": "Salt Lake City",
"state": "Utah",
"country": "USA",
"postalCode": 84116
}
},
"constraints": {
"analyticsReportData": {
"forCraPurpose": true,
"applicantIsPersonalGuarantor": true,
"timeIntervalTypes": [
"HISTORICALLY"
]
}
},
"type": "phrbcra",
"status": "success",
"createdDate": 1579819592,
"reportRefreshNumber": 2,
"originalReportCreatedDate": 1607450357,
"startDate": 1512594823,
"endDate": 1575666823,
"days": 730,
"institutions": [
{
"id": "102105",
"name": "FinBank Profiles",
"urlHomeApp": "http://www.bank.example.com",
"accounts": [
{
"id": "1111",
"ownerName": "PATRICK & LORRAINE PURCHASER",
"ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859",
"ownerAsOfDate": 1579819592,
"name": "Checking",
"number": "XX1111",
"type": "checking",
"aggregationStatusCode": "0",
"currentBalance": 100000,
"availableBalance": 1000,
"balanceDate": 1614880526,
"transactions": [
{
"id": "00000001",
"amount": -81.7,
"postedDate": 1614859200,
"description": "TMOBILE*AUTO PAY",
"normalizedPayee": "T-Mobile",
"institutionTransactionId": "0000000000",
"category": "Mobile Phone"
},
{
"id": "00000002",
"amount": -81.7,
"postedDate": 1614859200,
"description": "TMOBILE*AUTO PAY",
"normalizedPayee": "T-Mobile",
"institutionTransactionId": "0000000000",
"category": "Mobile Phone"
}
],
"analytics": [
{
"transactionalAttributes": [
{
"attributeName": "CASH_OUTFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "CASH_INFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 5050,
"count": 100,
"mean": 50.5,
"median": 50.5,
"min": 1,
"max": 100,
"standardDeviation": 29.011491975882016,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [
"10",
"72",
"78",
"16",
"25",
"67",
"27",
"15",
"36",
"75",
"88",
"57",
"51",
"30",
"66",
"87",
"61",
"6",
"82",
"48",
"40"
],
"projectedValues": [],
"streamIds": [
"e6dd352d-67d3-4a6c-a7a0-68f1e994bb22"
],
"streamConfidences": null
},
{
"attributeName": "INSURANCE_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "TAX_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "DISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NONDISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_EXPENSES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_LOAN_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NSF_FEE_CHARGES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
}
],
"stateAttributes": [
{
"attributeName": "MISSED_RECURRING_EXPENSES",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "MISSED_RECURRING_LOAN_PAYMENTS",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "PAYMENT_RISK_SCORE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 19825,
"count": 732,
"mean": 27.083333333333332,
"median": 24,
"min": -1,
"max": 46,
"standardDeviation": 8.739575902668523,
"comparedToCohorts": [],
"beginningValue": -1,
"endingValue": 24
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": -900726.9199999999,
"count": 732,
"mean": -1230.501256830601,
"median": -1192.56,
"min": -3804.56,
"max": 1234.44,
"standardDeviation": 1628.527991127309,
"comparedToCohorts": [],
"beginningValue": -3804.56,
"endingValue": 1234.44
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
],
"streams": [
{
"id": "e6dd352d-67d3-4a6c-a7a0-68f1e994bb22",
"payor": "0",
"payee": "John Smith",
"cadence": 7,
"status": "inactive",
"recency": 118,
"earliestObservedDate": "2022-09-18T00:00:00",
"latestObservedDate": "2024-09-13T00:00:00",
"count": 100,
"sum": 5050,
"min": 1,
"max": 100,
"mean": 50.5,
"median": 50.5,
"standardDeviation": 29.011491975882016,
"minimumCadence": 0,
"maximumCadence": 58,
"medianCadence": 4,
"modeCadence": 2,
"standardDeviationCadence": 9.261506907846133,
"transactionIds": [
"0",
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"28",
"29",
"3",
"30"
]
}
]
}
]
},
{
"id": "2222",
"ownerName": "PATRICK & LORRAINE PURCHASER",
"ownerAddress": "7195 BELMONT ST. PARLIN, NJ 08859",
"ownerAsOfDate": 1579819592,
"name": "Checking",
"number": "XX1111",
"type": "checking",
"aggregationStatusCode": "0",
"currentBalance": 100000,
"availableBalance": 1000,
"balanceDate": 1614880526,
"transactions": [
{
"id": "00000005",
"amount": -81.7,
"postedDate": 1614859200,
"description": "TMOBILE*AUTO PAY",
"normalizedPayee": "T-Mobile",
"institutionTransactionId": "0000000000",
"category": "Mobile Phone"
},
{
"id": "00000006",
"amount": -81.7,
"postedDate": 1614859200,
"description": "TMOBILE*AUTO PAY",
"normalizedPayee": "T-Mobile",
"institutionTransactionId": "0000000000",
"category": "Mobile Phone"
}
],
"analytics": [
{
"transactionalAttributes": [
{
"attributeName": "CASH_OUTFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "CASH_INFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 5050,
"count": 100,
"mean": 50.5,
"median": 50.5,
"min": 1,
"max": 100,
"standardDeviation": 29.011491975882016,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [
"10",
"72",
"78",
"16",
"25",
"67",
"27",
"15",
"36",
"75",
"88",
"57",
"51",
"30",
"66",
"87",
"61",
"6",
"82",
"48",
"40"
],
"projectedValues": [],
"streamIds": [
"e6dd352d-67d3-4a6c-a7a0-68f1e994bb22"
],
"streamConfidences": null
},
{
"attributeName": "INSURANCE_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "TAX_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "DISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NONDISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_EXPENSES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_LOAN_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NSF_FEE_CHARGES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
}
],
"stateAttributes": [
{
"attributeName": "MISSED_RECURRING_EXPENSES",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "MISSED_RECURRING_LOAN_PAYMENTS",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "PAYMENT_RISK_SCORE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 19825,
"count": 732,
"mean": 27.083333333333332,
"median": 24,
"min": -1,
"max": 46,
"standardDeviation": 8.739575902668523,
"comparedToCohorts": [],
"beginningValue": -1,
"endingValue": 24
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": -900726.9199999999,
"count": 732,
"mean": -1230.501256830601,
"median": -1192.56,
"min": -3804.56,
"max": 1234.44,
"standardDeviation": 1628.527991127309,
"comparedToCohorts": [],
"beginningValue": -3804.56,
"endingValue": 1234.44
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
],
"streams": [
{
"id": "e6dd352d-67d3-4a6c-a7a0-68f1e994bb22",
"payor": "0",
"payee": "John Smith",
"cadence": 7,
"status": "inactive",
"recency": 118,
"earliestObservedDate": "2022-09-18T00:00:00",
"latestObservedDate": "2024-09-13T00:00:00",
"count": 100,
"sum": 5050,
"min": 1,
"max": 100,
"mean": 50.5,
"median": 50.5,
"standardDeviation": 29.011491975882016,
"minimumCadence": 0,
"maximumCadence": 58,
"medianCadence": 4,
"modeCadence": 2,
"standardDeviationCadence": 9.261506907846133,
"transactionIds": [
"0",
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"28",
"29",
"3",
"30"
]
}
]
}
]
}
]
}
],
"customerAnalytics": {
"transactionalAttributes": [
{
"attributeName": "CASH_OUTFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "CASH_INFLOW",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 5050,
"count": 100,
"mean": 50.5,
"median": 50.5,
"min": 1,
"max": 100,
"standardDeviation": 29.011491975882016,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [
"10",
"72",
"78",
"16",
"25",
"67",
"27",
"15",
"36",
"75",
"88",
"57",
"51",
"30",
"66",
"87",
"61",
"6",
"82",
"48",
"40",
"45",
"96",
"95"
],
"projectedValues": [],
"streamIds": [
"e6dd352d-67d3-4a6c-a7a0-68f1e994bb22"
],
"streamConfidences": null
},
{
"attributeName": "INSURANCE_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "TAX_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "DISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NONDISCRETIONARY_SPENDING",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_EXPENSES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "RECURRING_LOAN_PAYMENTS",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
},
{
"attributeName": "NSF_FEE_CHARGES",
"aggregatedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": null,
"count": 0,
"mean": null,
"median": null,
"min": null,
"max": null,
"standardDeviation": null,
"comparedToCohorts": []
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"transactionIds": [],
"projectedValues": [],
"streamIds": [],
"streamConfidences": null
}
],
"stateAttributes": [
{
"attributeName": "MISSED_RECURRING_EXPENSES",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "MISSED_RECURRING_LOAN_PAYMENTS",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 0,
"count": 732,
"mean": 0,
"median": 0,
"min": 0,
"max": 0,
"standardDeviation": 0,
"comparedToCohorts": [],
"beginningValue": 0,
"endingValue": 0
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "PAYMENT_RISK_SCORE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": 19825,
"count": 732,
"mean": 27.083333333333332,
"median": 24,
"min": -1,
"max": 46,
"standardDeviation": 8.739575902668523,
"comparedToCohorts": [],
"beginningValue": -1,
"endingValue": 24
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
},
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"timeIntervalType": "HISTORICALLY",
"periods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"sum": -900726.9199999999,
"count": 732,
"mean": -1230.501256830601,
"median": -1192.56,
"min": -3804.56,
"max": 1234.44,
"standardDeviation": 1628.527991127309,
"comparedToCohorts": [],
"beginningValue": -3804.56,
"endingValue": 1234.44
}
],
"cohortBenchmarkPeriods": [
{
"startDate": "2022-09-18",
"endDate": "2024-09-18",
"cohortValues": []
}
]
}
],
"projectedValues": []
}
],
"streams": [
{
"id": "e6dd352d-67d3-4a6c-a7a0-68f1e994bb22",
"payor": "0",
"payee": "John Smith",
"cadence": 7,
"status": "inactive",
"recency": 118,
"earliestObservedDate": "2022-09-18T00:00:00",
"latestObservedDate": "2024-09-13T00:00:00",
"count": 100,
"sum": 5050,
"min": 1,
"max": 100,
"mean": 50.5,
"median": 50.5,
"standardDeviation": 29.011491975882016,
"minimumCadence": 0,
"maximumCadence": 58,
"medianCadence": 4,
"modeCadence": 2,
"standardDeviationCadence": 9.261506907846133,
"transactionIds": [
"0",
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"28",
"29",
"3",
"30"
]
}
]
}
}
```
### PDF Version {#pdf-version}
A human-readable PDF version of the report is available which is great
for underwriters or any other manual viewing of the report. To receive a PDF
version of the report, set the `Accept` request header to
`application/pdf` - otherwise, the report is returned as JSON.
* Example Payment Risk Insights PDF report: [Payment_Risk_Insights_Example_Report.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/small-business/Payment_Risk_Insights_Example_Report.pdf) (662KB)
* How to read a Payment Risk Insights PDF report: [Payment_Risk_Insights_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/small-business/Payment_Risk_Insights_HTR.pdf) (1MB)
## Reading a Payment Risk Insights JSON Report {#reading-a-payment-risk-insights-json-report}
This section provides a detailed description of the structure and format of the Payment Risk Insights Report JSON report. It explains the key elements, fields, and their usage. Developers should use this as a reference when integrating, parsing, or processing the JSON report. The JSON report is generated to provide data in a structured and machine-readable format.
#### Payment Risk Insights Report Attributes {#payment-risk-insights-report-attributes}
| **Attribute** | **Definition** | **Type** |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
| ASSET_BALANCE | History of asset balances for the customer and their accounts. | State |
| NSF_FEE_CHARGES | Fees charged to the customer by their financial institution resulting from a lack of sufficient funds or low balance to cover a purchase. | Transactional |
| CASH_INFLOW | Credit transactions in a customer's account. | Transactional |
| CASH_OUTFLOW | Debit / Spend transactions in a customer's account. | Transactional |
| DISCRETIONARY_SPENDING | Spend towards expenses that are not required either for core business operations (in the case of a business customer) or living expenses (in the case of a consumer customer). | Transactional |
| NONDISCRETIONARY_SPENDING | Spend towards expenses that are required for core business operations or living expenses. | Transactional |
| INSURANCE_SPENDING | Payments made towards an insurance company. | Transactional |
| TAX_PAYMENTS | Payments made towards a tax collection agency such as the IRS. | Transactional |
| RECURRING_EXPENSES | Payments made towards expenses that typically recur over time. | Transactional |
| DIVIDEND_INCOME | Dividend income is received as a stock shareholder's right for owning equity in a publicly traded company. | Transactional |
| MISSED_RECURRING_EXPENSES | Payments toward recurring expenses that were missed by the customer during the reporting period. | State |
| RECURRING_LOAN_PAYMENTS | Payments made towards loans that recur over time. | Transactional |
| MISSED_RECURRING_LOAN_PAYMENTS | Payments toward loans that were missed by the customer during the reporting period. | State |
| PAYMENT_RISK_SCORE | A score value between 0 and 100 that indicates the riskiness of the customer to miss an upcoming payment. Higher values indicate higher risk. The score has four levels: Low (0-25), Medium (26-50), Medium-High (51-75), and High (76-100). | State |
### Sample JSON Report {#sample-json-report}
The JSON sample is an output of the PRI profile profile-2750-2756 used in the sandbox (for [your own testing](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profile) we recommend using profile_3400 with Finbank Profiles - A):
[phrbcra-profile-2750-2756.json](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/phrbcra-profile-2750-2756.json) (266KB)
### Time Interval Types {#time-interval-types}
A report supports up to two time interval types. If a partner requests for more than two interval types, then the end point gives the error `More than 2 intervalTypes passed request.` If the time interval type is not specified, the default is MONTHLY_CALENDAR. The table shows all possible time interval types for which a partner can request a report.
| Time Interval Type | Description | First (Earliest) period may be partial | First (Most recent) period may be partial | Shortest possible period length | Longest possible period length |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|-------------------------------------------|---------------------------------|--------------------------------|
| DAILY | The report will be broken up into one period for every calendar date in the report time period. | NO | NO | 1 | 1 |
| WEEKLY_CALENDAR | The report time period will be broken up into periods of seven calendar dates, with each period beginning on a Monday and ending on a Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 7 |
| WEEKLY_ROLLING_7 | The report time period will be broken up into periods of seven calendar dates, counting backwards from the report end date. | YES | NO | 1 | 7 |
| BI_WEEKLY_CALENDAR | The report time period will be broken up into periods of 14 calendar dates, with each period beginning on a Monday and ending on the second subsequent Sunday, with the exception of the first and last periods which may be partial. | YES | YES | 1 | 14 |
| BI_WEEKLY_ROLLING_14 | The report time period will be broken up into periods of 14 calendar dates, counting backwards from the report end date. | YES | NO | 1 | 14 |
| SEMI_MONTHLY_CALENDAR | The report time period will be broken up into exactly two periods per calendar month, where both the first and the last period may be partial, and periods will alternate between representing the 1st-15th of the month and the 16th-end of the month. | YES | YES | 1 | 16 |
| MONTHLY_CALENDAR | The report time period will be broken up into one period per calendar month. | YES | YES | 1 | 31 |
| MONTHLY_ROLLING_30 | The report time period will be broken up into 11 periods of 30 calendar dates followed by one period of 35 (or 36 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 36 |
| QUARTERLY_CALENDAR | The report time period will be broken up into one period per three calendar months, where both the first and last period may be partial. | YES | YES | 1 | 92 |
| QUARTERLY_ROLLING_90 | The report time period will be broken up into three periods of 90 calendar dates followed by one period of 95 (or 96 for leap years) calendar dates to make one full calendar year, starting backwards from the report end date. | YES | NO | 1 | 96 |
| ANNUALLY | The report time period will be broken up into periods of 365 calendar dates (or 366 for leap years), starting backwards from the report end date. | YES | NO | 1 | 366 |
| HISTORICALLY | The report time period will be represented by exactly one period. | NO | NO | 1 | Duration of report data |
The JSON snippet shows an example of how a time interval type is represented.
* JsonS
```jsonS
"constraints": {
"analyticsReportData": {
"timeIntervalTypes": [
"MONTHLY_CALENDAR",
"ANNUALLY"
]
}
}
```
### JSON report structure - Analytics section {#json-report-structure---analytics-section}
Analytics will be provided at the account level, grouped by financial institution and at an aggregated customer level. The following examples show a customer with two accounts that contain transactions.
* Json
```json
"accounts": [
{"id": 3034460414},
{"id": 3034460415}
]
```
The analytics section is divided into three sections.
* Transactional attributes
* State attributes
* Streams
**Account-level analytics structure**
This section is for each of the customer accounts.
* Json
```json
"analytics": {
"transactionalAttributes": [...
],
"stateAttributes": [...
],
"streams": [...
]
}
```
**Customer-level analytics structure**
* Json
```json
"customerAnalytics": {
"transactionalAttributes": [...
],
"stateAttributes": [...
],
"streams": [...
]
}
```
#### Transactional attributes {#transactional-attributes}
Transactional attributes are based on a unit of data being a transaction itself. They are evaluated as events in time. A transactional attribute represents some classification or categorization of a customer's underlying transactions. For example, an attribute called DWELLING_EXPENSES may be a classification of all transactions that we assume to be a customer paying towards a mortgage, rent, home insurance and so on.
The following sample JSON snippets are for transactional attributes at an accounts and customer level.
* The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months.
* The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates.
* Not all attributes are showcased. Refer to the attribute table to view all PRI attributes.
* The data in the snippets are for profile-2750-2756 with some modifications.
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 1,
"endDate": "2023-07-31",
"max": -7.16,
"mean": -7.16,
"median": -7.16,
"min": -7.16,
"standardDeviation": 0.14142135623730964,
"startDate": "2023-07-01",
"sum": -7.16,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-07-01",
"endDate": "2023-07-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 7,
"endDate": "2024-03-04",
"max": -12.17,
"mean": -7.55,
"median": -7.16,
"min": -3.07,
"standardDeviation": 0.14142135623730964,
"startDate": "2023-03-05",
"sum": -42.96,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_OUTFLOW",
"streamIds": [
"107337ef-fa51-48cf-a70b-81144fb1e6e8"
],
"transactionIds": [
"101500062955",
"101500062933",
"101500062908",
"101500062911",
"101500062974",
"101500062918",
"101500062980"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 2,
"endDate": "2023-07-31",
"max": -9.75,
"mean": -6.888888,
"median": -6.888888,
"min": -4.01,
"standardDeviation": -4.0587929,
"startDate": "2023-07-01",
"sum": -13.76,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-07-01",
"endDate": "2023-07-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 5,
"endDate": "2024-03-04",
"max": -14.01,
"mean": -8.10,
"median": -7.85,
"min": -3.94,
"standardDeviation": 0.45253246733731172,
"startDate": "2023-03-05",
"sum": -47.46,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_OUTFLOW",
"streamIds": [
"5c6c913a-62dc-4d07-b4ed-28fbb68f9995"
],
"transactionIds": [
"101500063007",
"101500063020",
"101500062990",
"101500063028",
"101500063033"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
* Json
```json
"transactionalAttributes": [
{
"aggregatedByTimePeriods": [
{
"periods": [
{
"count": 3,
"endDate": "2023-07-31",
"max": -9.75,
"mean": -7.16,
"median": -7.16,
"min": -3.07,
"standardDeviation": 0.0,
"startDate": "2023-07-01",
"sum": -14.32,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-12-01",
"endDate": "2023-01-01",
"cohortValues": []
}
]
},
{
"periods": [
{
"count": 12,
"endDate": "2024-03-04",
"max": -14.01,
"mean": -7.69,
"median": -7.51,
"min": -3.07,
"standardDeviation": 0.25061422791045044,
"startDate": "2023-03-05",
"sum": -90.42,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
}
]
}
],
"attributeName": "CASH_OUTFLOW",
"streamIds": [
"107337ef-fa51-48cf-a70b-81144fb1e6e8",
"5c6c913a-62dc-4d07-b4ed-28fbb68f9995"
],
"transactionIds": [
"101500062955",
"101500062933",
"101500062908",
"101500062911",
"101500062974",
"101500062918",
"101500062980",
"101500063007",
"101500063020",
"101500062990",
"101500063028",
"101500063033"
],
"projectedValues": [],
"streamConfidences": null
}
]
```
**JSON fields description**
| Key (Datatype) | Description | Applicable for PRI |
|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------|
| aggregatedByTimePeriods (object) | An object that contains periods object data, comparedToCohorts object data, and time interval type. | Yes |
| periods (object) | Statistics of aggregated transactions over some time period. | Yes |
| count (number) | For the selected time interval type, the number of transaction events that occurred during the period. For example, for monthly time interval, count will be shown for each month of a year. | Yes |
| endDate (string) | For the selected time interval type, the final day (inclusive) of the period being reported. For example, for monthly time interval, endDate will be shown for each month of a year. | Yes |
| max (number) | For the selected time interval type, the maximum value of all transaction amounts in the period. For example, for monthly time interval, max will be shown for each month of a year. | Yes |
| mean (number) | For the selected time interval type, the mean value of all transaction amounts in the period. For example, for a monthly time interval, mean will be shown for each month of a year. | Yes |
| median (number) | For the selected time interval type, the median value of all transaction amounts in the period. For example, for a monthly time interval, the median will be shown for each month of a year. | Yes |
| min (number) | For the selected time interval type, the minimum value of all transaction amounts in the period. For example, for a monthly time interval, the min will be shown for each month of a year. | Yes |
| standardDeviation (number) | For the selected time interval type, the standard deviation of all transaction amounts in the period. For example, for a monthly time interval, the standardDeviation will be shown for each month of a year. | Yes |
| startDate (string) | For the selected time interval type, the first day (inclusive) of the period being reported. For example, for a monthly time interval, the startDate will be shown for each month of a year. | Yes |
| sum (number) | For the selected time interval type, the arithmetic sum of the amounts of all transactions in the period. For example, for a time interval, the sum will be shown for each month of a year. | Yes |
| comparedToCohorts (object) | An array of elements comparing the customer's income / spending during a time period to the average customer's income / spending in various cohorts, such as postal code, during the same time period. | No |
| cohortType (string) | Describes the type of cohort being compared to for this period, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No |
| totalDifferenceToCohort (number) | Reflects the difference between the customer's income / spending value for the period minus that of the average income / spending in this cohort. This field will be empty as it is not applicable for PRI. | No |
| percentageDifferenceToCohort (number) | Reflects the percentage difference between the customer's income / spending value for the period and the average income / spending of the cohort. This field will be empty as it is not applicable for PRI. | No |
| timeIntervalType (string) | Refer to Time Interval Types for how each period is defined. | Yes |
| cohortBenchmarkPeriods (object) | A list of objects where each object is a period of the same duration as those in aggregatedByTimePeriods, describing the income / spending of cohorts in the customer's zip code during that period for an attribute. | No |
| startDate (string) | The first day of the cohort benchmark period. | No |
| endDate (string) | The final day of the cohort benchmark period. | No |
| cohortValues (object) | An object that contains the type and value of a cohort benchmark period. This field will be empty as it is not applicable for PRI. | No |
| cohortType (string) | For each cohort benchmark period, the type of cohort we have a representative metric for, for example POSTAL_CODE. This field will be empty as it is not applicable for PRI. | No |
| value (number) | For each cohort benchmark period, the average income / spending for the cohort during this time period. This field will be empty as it is not applicable for PRI. | No |
| attributeName (string) | Name of the transactional / state / stream attribute that we are reporting the numbers for. Refer to the Payment Risk Insights Report Attributes. | Yes |
| streamIds | List of stream IDs associated with the attribute. | Yes |
| transactionIds(object) | List of transaction IDs associated with the attribute (a classification). | Yes |
| projectedValues (object) | List of projection objects, where each object indicates the projected income / spending value of the attribute over some coming period of time. This field will be empty as it is not applicable for PRI. | No |
| timeUnit (string) | The unit of time being described, for example MONTHS. This field will be empty as it is not applicable for PRI. | No |
| timeValue (number) | The number of timeUnit units for which we are projecting, for example 12 (for 12 months). This field will be empty as it is not applicable for PRI. | No |
| projectionValue (number) | The predicted sum value of the attribute over the coming timeValue number of timeUnits. This field will be empty as it is not applicable for PRI. | No |
| streamConfidences (object) | List of stream confidences, indicating the confidence in which we believe each stream is correctly associated with this attribute. | Yes |
| streamId (string) | The stream ID for which we are reporting the confidence. | Yes |
| confidence (number) | A float value between 0 and 100. | Yes |
#### State Attributes {#state-attributes}
The unit of data for state attributes is some generic "state" at a point in time. Whereas transactional attributes are based on specific events (the posting of a transaction), state attributes make some inference about a point in time based on an assembly of underlying data. Examples of state attributes include the balance of an account over time, a calculation based on underlying transactions in a time period (such as net cash flow), or other calculations such as a debt-to-income ratio.
The following sample JSON snippets are for state attributes at an accounts and customer level.
* The sample snippets show transaction data of one month for MONTHLY_CALENDAR time interval type as an example. The actual report has all transaction stats for all the months.
* The period array for ANNUALLY shows aggregated data for all the months between the specified start and end dates.
* Not all attributes are showcased. Refer to the attribute table to view all PRI attributes.
* The data in the snippets are for profile-2750-2756 with some modifications.
* Json
```json
"stateAttributes": [
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 325.06,
"count": 31,
"endDate": "2023-07-31",
"endingValue": 332.22,
"max": 332.22,
"mean": 328.6909677419355,
"median": 332.12,
"min": 324.96,
"standardDeviation": 3.639724673505515,
"startDate": "2023-07-01",
"sum": 10189.42,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-07-01",
"endDate": "2023-07-31",
"cohortValues": []
},
]
},
{
"periods": [
{
"beginningValue": 635.44,
"count": 365,
"endDate": "2024-03-04",
"endingValue": 401.56,
"max": 696.23,
"mean": 404.1959871413877,
"median": 410.06,
"min": 299.36,
"standardDeviation": 3.997490676405987,
"startDate": "2023-03-05",
"sum": 147785.90,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
},
]
}
],
"projectedValues": []
}
]
```
* Json
```json
"stateAttributes": [
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 506.78,
"count": 31,
"endDate": "2023-07-31",
"endingValue": 479.07,
"max": 510.89,
"mean": 494.6909677419355,
"median": 492.12,
"min": 461.96,
"standardDeviation": 4.75837468734,
"startDate": "2023-07-01",
"sum": 15497.36,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-07-01",
"endDate": "2023-07-31",
"cohortValues": []
}
]
},
{
"periods": [
{
"beginningValue": 595.94,
"count": 365,
"endDate": "2024-03-04",
"endingValue": 631.59,
"max": 652.23,
"mean": 610.387463784,
"median": 601.06,
"min": 451.36,
"standardDeviation": 4.862563462,
"startDate": "2023-03-05",
"sum": 224670.10,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
},
]
}
],
"projectedValues": []
},
]
```
* Json
```json
"stateAttributes": [
{
"attributeName": "ASSET_BALANCE",
"reportedByTimePeriods": [
{
"periods": [
{
"beginningValue": 831.84,
"count": 31,
"endDate": "2023-07-31",
"endingValue": 811.29,
"max": 510.89,
"mean": 406.381935483871,
"median": 413.24,
"min": 324.96,
"standardDeviation": 4.27944934701103,
"startDate": "2023-07-01",
"sum": 25686.78,
"comparedToCohorts": []
}
],
"timeIntervalType": "MONTHLY_CALENDAR",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-04-01",
"endDate": "2023-04-30",
"cohortValues": []
}
]
},
{
"periods": [
{
"beginningValue": 1231.38,
"count": 365,
"endDate": "2024-03-04",
"endingValue": 1033.15,
"max": 696.23,
"mean": 505.387463784,
"median": 499.06,
"min": 299.36,
"standardDeviation": 4.382563462,
"startDate": "2023-03-05",
"sum": 372455.0,
"comparedToCohorts": []
}
],
"timeIntervalType": "ANNUALLY",
"cohortBenchmarkPeriods": [
{
"startDate": "2023-03-05",
"endDate": "2024-03-04",
"cohortValues": []
},
]
}
],
"projectedValues": [],
}
]
```
**Description of JSON fields**
| Key (Datatype) | Description |
|--------------------------------|------------------------------------------------------------------|
| reportedByTimePeriods (object) | Value of the state over some time periods. |
| beginningValue (number) | Value of the state as reported on the startDate of the period. |
| endingValue (number) | Value of the state as reported on the endDate of the period. |
| count (number) | Occurrences of the state between specified startDate and enDate. |
#### Streams {#streams}
Streams are groups of transactions that represent a repeated flow of funds for some consistent purpose between two parties or accounts, if the same entity owns both the source and destination of funds. Examples of streams include bi-weekly paychecks from an employer to an employee, a customer's monthly phone bill paid to a telecom provider, a customer's monthly transfer from a checking account to an investment account, and so on. Since a stream is a group of transactions, a transactional attribute can assign a list of streams to itself if the transactions in that stream all fit the same classification being described by the attribute.
**JSON snippets of stream attributes:**
* Json
```json
"streams": [
{
"cadence": 20,
"id": "107337ef-fa51-48cf-a70b-81144fb1e6e8",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": 2023-03-05T00:00:00,
"latestObservedDate": 2024-02-04T00:00:00,
"count": 7,
"sum": -42.96,
"status": "active",
"min": -3.07,
"max": -12.17,
"mean": -7.55,
"median": -7.16,
"standardDeviation": 0.14142135623730964,
"minimumCadence": 5,
"maximumCadence": 9,
"medianCadence": 6,
"modeCadence": 6,
"standardDeviationCadence": 7.068617626733007,
"transactionIds": [
"101500062955",
"101500062933",
"101500062908",
"101500062911",
"101500062974",
"101500062918",
"101500062980"
]
}
]
```
* Json
```json
"streams": [
{
"cadence": 20,
"id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 20,
"earliestObservedDate": 2023-03-05T00:00:00,
"latestObservedDate": 2024-02-14T00:00:00,
"count": 5,
"sum": -47.46,
"status": "active",
"min": -3.94,
"max": -14.01,
"mean": -8.10,
"median": -7.85,
"standardDeviation": 0.45253246733731172,
"minimumCadence": 3,
"maximumCadence": 7,
"medianCadence": 4,
"modeCadence": 4,
"standardDeviationCadence": 5.172827626734145,
"transactionIds": [
"101500063007",
"101500063020",
"101500062990",
"101500063028",
"101500063033"
]
}
]
```
* Json
```json
"streams": [
{
"cadence": 20,
"id": "107337ef-fa51-48cf-a70b-81144fb1e6e8",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 30,
"earliestObservedDate": 2023-03-05T00:00:00,
"latestObservedDate": 2024-02-04T00:00:00,
"count": 7,
"sum": -42.96,
"status": "active",
"min": -3.07,
"max": -12.17,
"mean": -7.55,
"median": -7.16,
"standardDeviation": 0.14142135623730964,
"minimumCadence": 5,
"maximumCadence": 9,
"medianCadence": 6,
"modeCadence": 6,
"standardDeviationCadence": 7.068617626733007,
"transactionIds": [
"101500062955",
"101500062933",
"101500062908",
"101500062911",
"101500062974",
"101500062918",
"101500062980"
]
},
{
"cadence": 20,
"id": "5c6c913a-62dc-4d07-b4ed-28fbb68f9995",
"payee": "JOHN DOE",
"payor": "walmart",
"recency": 20,
"earliestObservedDate": 2023-03-05T00:00:00,
"latestObservedDate": 2024-02-14T00:00:00,
"count": 5,
"sum": -47.46,
"status": "active",
"min": -3.94,
"max": -14.01,
"mean": -8.10,
"median": -7.85,
"standardDeviation": 0.45253246733731172,
"minimumCadence": 3,
"maximumCadence": 7,
"medianCadence": 4,
"modeCadence": 4,
"standardDeviationCadence": 5.172827626734145,
"transactionIds": [
"101500063007",
"101500063020",
"101500062990",
"101500063028",
"101500063033"
]
}
]
```
**Description of JSON fields**
| Key (Datatype) | Description |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| cadence (number) | The average number of days elapsed between consecutive transactions in the stream. |
| id (string) | A randomly generated UUID to uniquely identify the stream. |
| payee (string) | The party that is receiving the funds. |
| payor (string) | The party that is sending the funds. |
| recency (number) | The number of days elapsed since the most recent transaction in the stream. |
| earliestObservedDate (string) | The date-time of the first observed transaction in the stream. |
| latestObservedDate (string) | The date-time of the last observed transaction in the stream. |
| status (string) | Active or inactive, depending on if the duration since the last transaction in the stream exceeds the historically observed cadence. |
| minimumCadence (number) | The smallest observed duration of time elapsed between any two consecutive transactions in the stream. |
| maximumCadence (number) | The largest observed duration of time elapsed between any two consecutive transactions in the stream. |
| medianCadence (number) | The median number of days elapsed between consecutive transactions in the stream. |
| modeCadence (number) | The most frequently observed number of days elapsed between consecutive transactions in the stream. |
| standardDeviationCadence (number) | The standard deviation of the number of days elapsed between consecutive transactions in the stream. |
| transactionIds (object) | A list of all the transaction IDs that were assigned to the stream. |
## Testing {#testing}
Ensure you use a test profile that contains supported account types such
as [profile_3400](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payment-risk-insights-report-profile).