# Verification of Income and Employment - Payroll source: https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voie-payroll/index.md ## Overview {#overview} The Verification of Income and Employment -- Payroll (VOIE-Payroll) product provides insights into the consumer's income and employment. The report includes employment details, including employer name, employment status, and other employment information as available. The report also includes income details, including a summary of annual payments for the current year to date through prior year two, as well as other pay period payment history details as available. 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} * **Employment Summary:** Employer name, address, hire date, latest pay date, employment status, etc * **Income Summary:** Pay frequency, pay rate, annual income summary, estimated monthly income, payment histories (as available), etc #### Additional Product Information {#additional-product-information} * **Report Generation Time (median):** * Direct API payroll accounts: Less than 5 seconds * Credentialed payroll accounts: Less than 2 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) Payroll product. * **Supported Report Format:** JSON and PDF Note: This report may ONLY be furnished for a Fair Credit Reporting Act (FCRA) purpose such as credit, insurance, or employment, and only pursuant to a permissible purpose certification by the report user. Provision and use of this report is subject to all applicable obligations of the FCRA. ### Use Cases {#use-cases} The VOIE -- Payroll product is suitable 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 Data Connect. Refer to [Generating Reports](https://developer.mastercard.com/open-finance-us/documentation/products/lend/generating-reports/index.md) for more information. * [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-connect-flow) ### Generate VOIE -- Payroll Report {#generate-voie----payroll-report} To generate or refresh a VOIE -- Payroll report, use the following endpoint: API Reference: `POST /decisioning/v2/customers/{customerId}/voiePayroll` The response will include 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} * VOIE -- Payroll reports may be refreshed as VOE -- Payroll reports for mortgage lending if updated income information is not desired in the new report. See [VOE -- Payroll](https://developer.mastercard.com/open-finance-us/documentation/products/lend/reports/voe-payroll/index.md) for more information. * Use the `paystatementFromDate` parameter to customize the payment history included in the report. If not used, the report will default to including the full history through prior year two, as available. ### Get VOIE -- Payroll Report {#get-voie----payroll-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": "41h4nzppn37u-voiepayroll", "portfolioId": "9qud7dtuzbew-1-port", "gseEnabled": true, "customerType": "active", "customerId": 1275320, "requestId": "7a7qyps2iy", "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" }, "type": "voiePayroll", "reportStyle": "credentialedPayroll", "status": "success", "createdDate": 1579819592, "title": "Mastercard Open Banking Verification of Income and Employment - Payroll", "constraints": { "payrollData": { "payrollAccountIds": [ "018b8f10-fdf8-0ef7-ded5-34a17c34d86f" ], "payrollAggregatorResponseId": "4baxktu9wdda" }, "reportCustomFields": { "label": "loanID", "value": "12345", "shown": true } }, "employmentHistory": { "asOfDate": 1596175200, "employmentId": "vkvxszcy7nc9c19d", "employerName": "ACME INC", "payrollSource": "argyle", "payrollProvider": "Paychex", "employee": { "name": "John Doe Smith", "givenName": "John", "middleName": "Doe", "familyName": "Smith", "address": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ] }, "employment": { "employerName": "ACME INC", "legalEntityId": "752760000", "originalHireDate": 1527832800, "latestHireDate": 1527832800, "latestPayDate": 1596175200, "daysSinceLastPay": 10, "numberPayCadenceWithoutPay": 1, "employmentEndDate": 1527832800, "employmentDuration": "P1Y6M0D", "employerAddress": [ { "address1": "Address 1", "city": "City", "state": "TX", "zip": "99999" } ], "employmentStatusCode": "A", "employmentStatusName": "Active", "workLevelCode": "FT", "workLevelName": "Full Time-Regular", "workLevelStatus": "Full Time", "positionTitle": "Shift Supervisor", "positionDuration": "P1Y6M0D" }, "income": { "payFrequency": "Weekly", "payType": "Hourly", "basePayRate": 27.5, "annualIncome": [ { "year": "2021", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 }, { "year": "2020", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 }, { "year": "2019", "grossPayAmountYTD": 73925.12, "netPayAmountYTD": 73925.12, "basePayAmountYTD": 73925.12, "overtimePayAmountYTD": 100.01 } ], "monthlyIncome": { "estimatedMonthlyBasePay": 2000, "estimatedMonthlyOvertimePay": 100 }, "directPayStatements": [ { "payrollPayHistoryId": "cy1a742k28", "lastPayPeriodIndicator": true, "mainPayStatementFields": { "payDate": 1596175200, "startDate": 1595138400, "endDate": 1595656800, "payPeriodHours": 40, "payFrequency": "Weekly", "payType": "Hourly", "grossPayAmount": 1888.75, "grossPayAmountYTD": 73925, "netPayAmount": 1401.95, "netPayAmountYTD": 73925 }, "earnings": [ { "name": "basePayAmount", "type": "base", "rate": 27.5, "amount": 1100, "amountYTD": 5500 } ], "deductions": [ { "type": "Federal tax", "amount": 143.45 }, { "type": "State tax", "amount": 12.5 } ] } ] } } } ``` 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 -- Payroll report: [VOIE_Payroll_HTR.pdf](https://static.developer.mastercard.com/content/open-finance-us/uploads/reports/lend/VOIE_Payroll_HTR.pdf) (2MB) ### 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 is indicated as supporting Payroll such as [Homer Loanseeker](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#payroll-profiles).