# Verification of Income and Employment - Paystub (with TXVerify)
source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-paystub/index.md
## Overview {#overview}
The Verification of Income and Employment -- Paystub with Transaction Verify (VOIE-Paystub with TXVerify) product provides insights into the consumer's income and employment. The report includes digitized pay statement details, account information, and may include up to twenty-four months of income stream credit transaction history, and details of the matching of the pay statement details to the direct deposit transaction(s).
Learn more about Mastercard's [Income \& Employment](https://developer.mastercard.com/open-finance-us/documentation/products/lend/product-solutions/index.md#income--employment) products.
#### Key Product Features {#key-product-features}
* **Account Owner:** See the listed account owner name and address to assist in fraud reduction
* **Deposit Income Streams**: Provides the full 24 months of deposit history as available. Defaults to only include Moderate and High confidence income streams, but can be adjusted to include Low confidence streams as well
* **Digitized Paystub Details:** Includes pay statement, employer, and employee details using our OCR technology
* **Estimated Monthly Income:** Estimates for base, bonus, and other pay types
* **Transaction Verify - Income and Employment Matching Summary:** Results of the matching of the digitized paystub details to the direct deposit transaction(s)
#### 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** : Verification of Income (VOI). 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 6 minutes
* **Report Refreshes:** This report can be refreshed with new data as long as the accounts are still connected, and consent is active. Refreshes are provided at no cost within 60 days after the first report is created. A report pulled after this period will incur a new charge. This report may also be refreshed as a Verification of Employment (VOE) Transactions product.
* **Supported Account Types**: Checking, Savings, Money Market
#### Use Cases {#use-cases}
The VOIE -- Paystub (with TXVerify) product can be used for the following use cases:
* Auto
* Credit Card Issuance
* Credit Line Management
* Customer / Portfolio Monitoring
* Debt Collection
* [Mortgage Lending](https://developer.mastercard.com/open-finance-us/documentation/usecases/mortgage-lending/index.md)
* Personal Financial Management
* Personal Lending
* Servicing
* Small and Medium Business
* Tenant Screening
## How it Works {#how-it-works}
### Prerequisites {#prerequisites}
This product is dependent on the customer linking their bank accounts via Mastercard Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. The product also requires access to the customer's paystub, which can be uploaded via the Data Connect application, or collected by the client and shared via the API (see below for details).
* [Generate the required credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials)
* [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token)
* [Create a customer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#active-customers)
* [Create a consumer record](https://developer.mastercard.com/open-finance-us/documentation/customer-records/index.md#consumers)
* [Generate a Data 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 VOIE -- Paystub (with TXVerify) Report {#generate-voie----paystub-with-txverify-report}
Refer to [Generating Reports Using the API](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-the-api) for general information on report generation.
There are two ways to generate a VOIE -- Paystub (with TXVerify) report:
* automated report generation at the end of a Data Connect Full session
* client-initiated API report generation
There are some specific nuances for client-initiated API VOIE -- Paystub (with TXVerify) report generation that are described below.
To generate or refresh a VOIE -- Paystub (with TXVerify) report, use the following steps:
**1. Data Connect Bank Accounts**
Have the consumer connect to their bank account(s) where they deposit their pay. Find more information on account connection in [Generating Reports Using Data Connect](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#generating-reports-using-data-connect). If the consumer has already connected accounts previously, move to the next step.
**2. Collect the consumer's recent paystub**
File requirements:
* Upload the most recent paystub for each employer (limit is 3 files)
* One file can only contain the details for one paystub
* Acceptable file types: `pdf`, `png`, or `jpeg`
* The file size limit is 25 MB
* No bank statements or non-paystub images
* No password-protected PDF files
**3. Store the consumer's paystub and get an asset ID**
API Reference: `POST /aggregation/v1/customers/{customerId}/payStatements`
**4. Generate the VOIE -- Paystub (with TXVerify) report**
API Reference: `POST /decisioning/v2/customers/{customerId}/voieTxVerify/withInterview`
The response includes the status of the report generation and a
report ID. A notification is sent when report generation is finished
(see [Report Webhooks](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-report/index.md)).
#### Implementation Notes {#implementation-notes}
* The assetId returned in step 3 is used to indicate which paystub files should be included in the report.
* Use the `fromDate` parameter to customize the transaction history included in the report, up to 24 months maximum. By default, 2 months of history will be aggregated as available. The income stream transactions will always show the full history, up to 24 months as available.
* Customize which accounts are included in the report using the `accountIds` parameter. By default, the report includes all supported account types.
* Customize the income streams returned in this report based on the confidence level. This input is called `incomeStreamConfidenceMinimum`. All income streams whose confidence level is greater than or equal to the number requested are provided. By default, the report will default to only include Moderate and High confidence income streams.
* High confidence levels correspond to `confidence` values of 75 and 100.
* Moderate confidence levels correspond to a `confidence` value of 50
* Low confidence levels correspond to `confidence` values of 0 and 25
* Streams with confidence levels of Moderate or High are considered income. Streams with a confidence level of Low are considered non-income. Receiving all income streams may be desirable based on the use case.
### Get VOIE -- Paystub (w/ TXVerify) Report {#get-voie----paystub-w-txverify-report}
Once the report is generated, retrieve the report using one of the [Get Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/get-reports/index.md) endpoints.
#### Example Report {#example-report}
The Get Report APIs 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": "2f3z55zuwewm-voietxverify",
"customerId": 1275320,
"consumerId": "3f7ff2cf0ffb3d0cd59875e070c9b1d4",
"consumerSsn": "6789",
"disputeStatement": "Invalid data present.",
"requesterName": "Decisioning API",
"endUser": {
"name": "ABC Apartments",
"address": "123 Main St",
"city": "Murray",
"state": "UT",
"zip": "84123",
"phone": "555-2106",
"email": "customerservice@example.com",
"url": "example.com"
},
"requestId": "7a7qyps2iy",
"type": "voieTxVerify",
"status": "success",
"createdDate": 1579819592,
"title": "Verification of Income and Employment - Paystub (with TXVerify)",
"constraints": {
"accountIds": [
"1000535275",
"6001966284"
],
"fromDate": 1620322948,
"voieWithInterviewData": {
"txVerifyInterview": [
{
"assetId": "6f8fb0a0-e882-4f57-b672-cf53f1397581",
"accounts": []
}
],
"extractEarnings": true,
"extractDeductions": false,
"extractDirectDeposit": true
},
"reportCustomFields": [
{
"label": "loanID",
"value": "12345",
"shown": true
},
{
"label": "trackingID",
"value": "5555",
"shown": true
}
],
"incomeStreamConfidenceMinimum": 50
},
"customerType": "active",
"portfolioId": "9qud7dtuzbew-13-port",
"numberOfBillableAssets": 1,
"reportStyle": "voieWithInterview",
"assetIds": [
"6f8fb0a0-e882-4f57-b672-cf53f1397581"
],
"payStatements": {
"payPeriod": "LastPayPeriod",
"billable": true,
"assetId": "6f8fb0a0-e882-4f57-b672-cf53f1397581",
"payDate": 1559241000,
"startDate": 1557513000,
"endDate": 1558722600,
"netPayCurrent": 1802.22,
"netPayYTD": 36000,
"grossPayCurrent": 24200,
"grossPayYTD": 72600,
"matchType": "NET_PAY_MATCH",
"employer": {
"name": "Rocket Surgery"
},
"employee": {
"name": "Patrick Purchaser"
},
"payStat": {
"name": "regular 1",
"type": "regular",
"description": "regular income",
"amountCurrent": 6000,
"amountYTD": 18000
},
"directDeposits": [
{
"fiName": "America First",
"accountType": "Checking",
"amountCurrent": 1744.61,
"description": "Payroll"
}
],
"monthlyIncome": {
"estimatedMonthlyBasePay": 2000,
"estimatedMonthlyOvertimePay": 50,
"estimatedMonthlyBonusPay": 20,
"estimatedMonthlyCommissionPay": 50,
"estimatedMonthlyOtherPay": 150,
"estimatedMonthlyTotalPay": 2120
},
"institutions": {
"id": 101732,
"name": "FinBank",
"urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp",
"accounts": {
"id": 1000023996,
"number": "1111",
"ownerName": "JOHN DOE",
"ownerAsOfDate": 1577986990,
"ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518",
"name": "Checking",
"type": "checking",
"availableBalance": 123.45,
"aggregationStatusCode": 0,
"balance": 123.45,
"balanceDate": 1588350276,
"averageMonthlyBalance": 301.45,
"transactions": [],
"details": {
"interestMarginBalance": -50000,
"availableCashBalance": 1500,
"vestedBalance": 300000,
"currentLoanBalance": 0,
"availableBalanceAmount": 2000
},
"incomeStream": {
"id": "dens28i3vsch-voitxverify2",
"name": "none",
"status": "ACTIVE",
"confidence": 70,
"cadence": {
"startDate": 1577986990,
"stopDate": 1587986990,
"days": 180
},
"netAnnual": 110475.7,
"projectedNetAnnual": 0,
"estimatedGrossAnnual": 0,
"projectedGrossAnnual": 151609,
"incomeStreamMonths": 24,
"averageMonthlyIncomeNet": 9206.31,
"transactions": [
{
"id": 100000527471,
"amount": 1802.22,
"postedDate": 1559241000,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"institutionTransactionId": "100000000",
"category": "Paycheck",
"payStatementMatchTypes": [
"DATE",
"NET_AMOUNT",
"DIRECT_DEPOSIT_AMOUNT",
"EMPLOYER_NAME",
"INCOME_STREAM_PAYCHECK"
]
}
]
},
"incomeStreams": [
{
"id": "dens28i3vsch-voitxverify2",
"name": "none",
"status": "ACTIVE",
"confidence": 70,
"cadence": {
"startDate": 1577986990,
"stopDate": 1587986990,
"days": 180
},
"netAnnual": 110475.7,
"projectedNetAnnual": 0,
"estimatedGrossAnnual": 0,
"projectedGrossAnnual": 151609,
"incomeStreamMonths": 24,
"averageMonthlyIncomeNet": 9206.31,
"transactions": [
{
"id": 100000527471,
"amount": 1802.22,
"postedDate": 1559241000,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"institutionTransactionId": "100000000",
"category": "Paycheck",
"payStatementMatchTypes": [
"DATE",
"NET_AMOUNT",
"DIRECT_DEPOSIT_AMOUNT",
"EMPLOYER_NAME",
"INCOME_STREAM_PAYCHECK"
]
}
]
}
]
}
}
},
"institutions": {
"id": 101732,
"name": "FinBank",
"urlHomeApp": "https://finbank.prod.fini.city/CCBankImageMFA/login.jsp",
"accounts": [
{
"id": 1000023996,
"ownerName": "JOHN DOE",
"ownerAddress": "924 GAINSVILLE HIGHWAY SUITE 130 BUFORD, GA 30518",
"ownerAsOfDate": 1577986990,
"name": "Checking",
"number": "1111",
"type": "checking",
"aggregationStatusCode": 0,
"incomeStreams": [
{
"id": "dens28i3vsch-voietxverify",
"name": "none",
"status": "ACTIVE",
"confidence": 70,
"cadence": {
"startDate": 1577986990,
"stopDate": 1587986990,
"days": 180
},
"netMonthly": [
{
"month": 1522562400,
"net": 2004.77
}
],
"netAnnual": 110475.7,
"projectedNetAnnual": 0,
"estimatedGrossAnnual": 0,
"projectedGrossAnnual": 151609,
"averageMonthlyIncomeNet": 9206.31,
"incomeStreamMonths": 24,
"transactions": [
{
"id": 100000527471,
"amount": 1802.22,
"postedDate": 1559241000,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"institutionTransactionId": "100000000",
"category": "Paycheck"
}
]
}
],
"balance": 123.45,
"averageMonthlyBalance": 301.45,
"transactions": [
{
"id": 100000527471,
"amount": 22.21,
"postedDate": 1582286400,
"description": "FINICITY INC PAYROLL",
"memo": "Finicity amount credit",
"investmentTransactionType": "dividend",
"normalizedPayee": "Finicity",
"institutionTransactionId": "100000000",
"category": "Paycheck",
"bestRepresentation": "FINICITY INC PAYROLL"
}
],
"details": {
"interestMarginBalance": -50000,
"availableCashBalance": 1500,
"vestedBalance": 300000,
"currentLoanBalance": 0,
"availableBalanceAmount": 1000,
"marginBalance": 100,
"currentBalance": 1000
},
"position": {
"id": 637054,
"currency": "USD",
"symbol": "MCD",
"securityName": "Common Stock",
"units": 5,
"marketValue": 1403.55,
"currentPrice": 280.71,
"securityType": "Stock"
},
"availableBalance": 123.45
}
]
}
}
```
A human-readable PDF version of the report is available which is great
for underwriters or any other manual viewing of the report.
How to read a VOIE -- Paystub (with TXVerify) report:
[VOIE_Paystub_Report_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Paystub_Report_HTR.pdf) (1MB)
## Testing {#testing}
Refer to [Generating Reports -- Testing](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md#testing).
Ensure you use a test profile that contains supported VOIE -- Paystub (w/ TXVerify)
account types and has a test paystub file download option, such as
[Jess Sea](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#paystub-profiles).