Banking SDK Example

### Create a user [Create a user](/api-reference/users/create-a-user) before ordering a verification. Include the following PII information in your request: | Field | Payroll verifications | Banking verifications | Document verifications | | -------------- | --------------------- | --------------------- | ---------------------- | | `first_name` | Required | Required | Required | | `last_name` | Required | Required | Required | | `ssn` | Not required | Required | Required | | `birth_date` | Not required | Required | Not required | | `address` | Not required | Required | Not required | | `phone_number` | Not required | Required | Not required | ```json theme={} { "first_name": "Jane", "last_name": "Doe", "ssn": "000-00-0000", "email": "jane@example.com", "phone_number": "+15555555555", "address": { "city": "New York", "line1": "123 Main St", "line2": null, "state": "NY", "country": "US", "postal_code": null }, "birth_date": { "year": 1990, "month": 1, "day": 13 }, "external_id": null, "external_metadata": { "suppress_verification": true } } ``` ### Order a verification Use [`POST /v2/verifications`](/api-reference/verifications/order-a-verification) for all verification types (payroll, banking, and documents). The shared request model works as follows: * `user` is required for all verification requests. * `report.type` determines whether the verification is payroll-based, banking-based, or documents-based. * `employments` is required for document verifications only. * `report.configuration` is used for banking verifications only. * `loan` and `billing` can be supplied for all verification types. Payroll verifications use `report.type = voie | voe` ```json theme={} { "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69", "report": { "type": "voie" }, "loan": { "number": "1234", "borrower_id": "ABC789", "application_id": "2121313", "officer_email": "john.doe@mortgage.com" }, "billing": { "cost_center": "5" } } ``` Banking verifications use `report.type = voa | voai | voi | voe-transactions` ```json theme={} { "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69", "report": { "type": "voai", "configuration": { "from_date": "2024-01-01T00:00:00Z", "income_stream_confidence_minimum": 50, "report_custom_fields": [ { "label": "loanID", "value": "12345", "shown": true } ] } }, "loan": { "number": "1234", "borrower_id": "ABC789", "application_id": "2121313", "officer_email": "john.doe@mortgage.com" }, "billing": { "cost_center": "5" } } ``` Mortgage document verifications use `report.type = doc-voi-mortgage` ```json theme={} { "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69", "employments": [ { "employer": "Warehouse Services Inc", "status": "active", "hire_date": "2023-02-01", "termination_date": null } ], "report": { "type": "doc-voi-mortgage" }, "loan": { "number": "1234", "borrower_id": "ABC789", "application_id": "2121313", "officer_email": "john.doe@mortgage.com" }, "billing": { "cost_center": "5" } } ``` ### Create a connection session *Skip this step for document verifications.* For payroll and banking verifications, create a session via [`POST /v2/sessions`](/api-reference/verifications/create-a-session). When the request succeeds, the response includes a `link` URL that launches the frontend session. Session links expire after one hour for security. A new session link can be created at any time by creating another session for the active verification. The verification used to create the session must be in an active state. Active means the verification is not completed and not cancelled. If no active verification exists, create a new verification first. The request requires a `verification` ID and accepts an optional `configuration` object:

Configuration property	Applies to	Description
`configuration.experience`	Banking only	Optional bank connection experience customization ID (provided by Argyle)
`configuration.single\_use\_url`	Banking only	Expires after one successful connection
`configuration.redirect\_url`	Payroll and banking	Redirect URL after session completion.
`configuration.flow\_id`	Payroll only	Optional payroll embedded connection experience customization ID
`configuration.items`	Payroll only	Limits Link to the provided Items. One Item opens that Item directly; multiple Items show only those Items.
`configuration.language`	Payroll only	Supported Link [display language](/link/initialization/overview#optional-initialization-parameters)
`configuration.mobile\_app`	Payroll only	Set to `true` if embedding in a mobile application, otherwise `false`

```json theme={} { "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "configuration": { "redirect_url": "https://your-application.com/return", "flow_id": "12ABCD3E", "language": "EN", "mobile_app": true } } ``` ```json theme={} { "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "configuration": { "experience": null, "single_use_url": false, "redirect_url": "https://your-application.com/return", "flow_id": "12ABCD3E", "language": "EN", "mobile_app": true }, "link": "https://connect.argyle.com/?...", "data_source": "payroll" } ``` ```json theme={} { "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "configuration": { "experience": "97f1eccb-241d-4052-8409-fab9e27a589b", "single_use_url": false, "redirect_url": "https://your-application.com/return" } } ``` ```json theme={} { "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "configuration": { "experience": "97f1eccb-241d-4052-8409-fab9e27a589b", "single_use_url": false, "redirect_url": "https://your-application.com/return" }, "link": "https://connect2.finicity.com?...", "data_source": "banking" } ``` ### Launch the frontend session Use the returned `link` based on the verification type. #### Payroll * **Payroll SDKs (recommended)** * Pass `link` as the `connectUrl` parameter when [initializing the Web SDK](/link/initialization/web#initialize-with-connecturl) or [Mobile SDKs](/link/initialization/mobile-sdks). * This is the default recommendation, including when you want to initialize Link inside an iframe as [Link callbacks](/link/reference/callbacks) remain available. * **Hosted Link** * On web, open the `link` URL in the same tab, a popup window, or a separate tab. * On mobile, open the `link` in a secure browser context such as `ASWebAuthenticationSession` on iOS or `Android Custom Tabs` on Android. * Hosted Link currently does not support callbacks. #### Banking * **Banking SDK (recommended)** * Pass `link` as the `connectURL` value when launching the banking SDK. * SDK callbacks support immediate frontend UX handling. For backend verification status, subscribe to the [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhook. * For SDK installation options and advanced configuration, refer to SDK docs. ```html theme={} Banking SDK Example

``` * **Hosted banking session** * Hosted or no-SDK banking flows must be enabled by Argyle before use. Reach out to your Argyle customer success manager before using this implementation path. * Set `configuration.redirect_url` so the user returns to your application. * On web, open the `link` URL in the same tab, a popup window, or a separate tab. * On mobile, open the `link` in a secure browser context such as `ASWebAuthenticationSession` on iOS or `Android Custom Tabs` on Android. * Do not default to opening the raw returned `link` directly in an iframe. ### Subscribe to webhooks Subscribe to the [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhook to track lifecycle events. Set `include_resource = true` so the webhook payload contains the full verification object inside `data.resource`. The most important verification `status.code` updates are: * `pending` — verification created * `user_session_started` — user opened the payroll or banking experience * `authenticated` — the user authenticated for payroll or banking and data aggregation is starting * `documents_processing` — uploaded documents are currently processing * `completed` — the report is ready for download These are the primary lifecycle updates. Additional state transitions can occur depending on the verification flow. ### Download reports and JSON When you receive a [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhook with `status.code = completed`, the `report` object in the webhook payload will contain the following download links: * `file_url` — PDF report * `json_url` — report in JSON format ```json theme={} { "event": "verifications.updated", "name": "name-for-the-webhook-subscription", "data": { "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69", "verification": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "resource": { "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b", "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69", "created_at": "2023-03-09T16:22:06.081Z", "updated_at": "2023-03-09T16:22:06.081Z", "channel": "api", "status": { "state": "COMPLETED", "code": "completed", "errors": [] }, "report": { "id": "2a14ce6f-3aed-4c15-8ea2-92a17b6edb95", "type": "doc-voi-mortgage", "file_url": "www.argyle.com/storagename/pdf", "json_url": "www.argyle.com/storagename/json" }, "employments": [ { "employer": "Starbucks", "status": "active", "hire_date": "2015-08-28", "termination_date": null } ], "loan": { "number": "1234", "borrower_id": "ABC789", "application_id": "2121313", "officer_email": "john.doe@mortgage.com" }, "billing": { "cost_center": "5" }, "data_source": "documents" } } } ``` GET requests to `file_url` and `json_url` require [Argyle authentication headers](/api-guide/overview#authentication). ## Re-Verifications

### Instant Refresh The refresh endpoint supports payroll, banking, and Doc VOI verifications. It returns a new verification ID and report. Use [`POST /v2/verifications/refresh`](/api-reference/verifications/refresh-a-verification) to create a **new** payroll or banking verification without the user needing to reconnect, as long as a valid connection is still available. For Doc VOI, use the same endpoint with `report.type = doc-voi-mortgage` to generate a new report from the user's existing uploaded documents without uploading additional documents. In most cases, instant refresh verifications move quickly to either `completed` or `cancelled`. ### Doc VOI with new documents To refresh a Doc VOI report with additional or updated documents, order a new `doc-voi-mortgage` verification for the same `user` with [`POST /v2/verifications`](/api-reference/verifications/order-a-verification). The request shape is the same as a new document verification, including the `employments` requirements. Argyle reuses the user's previously uploaded documents as the baseline for the new verification. After the new verification is created: 1. Upload each net-new document for the same `user` with [`POST /v2/user-uploads`](/api-reference/user-uploads/upload-a-document). 2. Listen for [`verifications.updated`](/api-reference/verifications-webhooks/updated) webhooks as the verification moves through document processing. 3. Retrieve the refreshed report from `report.file_url` or `report.json_url` when the verification is complete. ## Recovery options and error handling

### Connections not completed If the user closes the payroll or banking experience before completion, or the session link expires, the verification usually remains in `pending` or `user_session_started`. In this case, create a new session URL for the existing active verification with [`POST /v2/sessions`](/api-reference/verifications-guide#create-a-connection-session). ### User details missing or invalid If `POST /v2/verifications` returns a 400 response for missing or invalid user details: 1. Update the user with [`PATCH /v2/users/{id}`](/api-reference/users/update-a-user). 2. Retry `POST /v2/verifications`. ## Testing

### Payroll test profiles Use Argyle's [sample user credentials](/overview/sandbox-testing#connect-sample-users) in Link to connect to: * **Sandbox**: any employer or payroll provider * **Production**: `Platformtronic` or `Employertronic` For specific scenario testing, the following sample users are also available: | | Homer Loanseeker | Suzi Builder | Andy Freddie | | ------------------ | ----------------------------------------- | ------------------------------------- | ---------------------------------------- | | Email | homer\_loanseeker@argyle.com | suzi\_builder@argyle.com | andy\_freddie@argyle.com | | Username | homer\_loanseeker | suzi\_builder | andy\_freddie | | Password | passgood | passgood | passgood | | Verification code | 9081 | 9084 | 9088 | | Phone number | (800) 900-0101 | (800) 900-0104 | (800) 900-0108 | | Driver's license # | D1230101 | D1230104 | D1230108 | | **Returns** | **1 active employment** | **2 active employments** | **1 active and 1 terminated employment** | ### Banking test profiles When you're ready to begin testing, contact your Argyle Customer Success Manager to enable banking permissions. The Sandbox testing environment for banking supports a maximum of 500 users. To stay within this limit, implement user-management workflows and remove inactive users when they are no longer needed. The following sample test profiles can be connected to: * **Sandbox**: connect to `FinBank Profiles A` or `FinBank Profiles B` * **Production**: connect to `FinBank Billable` or `FinBank Oauth Billable` | Username | Password | Account types | Supported products | | ----------- | ----------- | ------------------------------------------------------------------------------ | -------------------------------------- | | profile\_02 | profile\_02 | Savings, IRA, 401k, Credit Card | `voa`, `voi`, `voai` | | profile\_03 | profile\_03 | Checking, Personal Investment, 401K, Roth, Savings (Joint Account owners) | `voa`, `voi`, `voai` | | profile\_04 | profile\_04 | Checking, 403B, 529, Rollover, Mortgage | `voa`, `voi`, `voai` | | profile\_05 | profile\_05 | Checking, Investment, Stocks, UGMA, UTMA (Joint Account owners) | `voa`, `voi`, `voai` | | profile\_06 | profile\_06 | Checking, Retirement, KEOGH, 457, Credit Card | `voa`, `voi`, `voai` | | profile\_07 | profile\_07 | Checking, Stocks, CD, Investment Tax-Deferred, Employee Stock | `voa`, `voi`, `voai` | | profile\_08 | profile\_08 | Checking, Primary Savings, Money Market, 401A, Line of credit | `voa`, `voi`, `voai` | | profile\_09 | profile\_09 | Checking, Savings, Checking failed report. Errors include `102`, `103`, `185`. | `voa`, `voi`, `voai` *(failed report)* | For specific scenario testing, the following sample users are also available: | | Sue Wealthy | River Paycheck | Alex Student | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Username | sue\_wealthy | river\_paycheck | alex\_student | | Password | profile\_700 | profile\_703 | profile\_704 | | Description | Sue is working as a Product Manager with a good steady income, a mortgage, and multiple investment accounts. She has a loan account and leases a car. Sue travels a few times a year. She has typical expenses like groceries, clothes, entertainment, gym membership, car expenses, and she has a pet. | River works in construction. He rents an apartment and has typical expenses like groceries, clothes, entertainment, household and car expenses. He has some savings but no investments, no loans and no credit cards. In some months, River's expenses exceed his income. | Alex is working full-time with a good salary but she is still paying off her student loan. She makes regular monthly repayments, but she still has over \$30,000 to pay off. Alex has typical expenses like groceries, clothes, entertainment, household, and car expenses. She has limited savings and she has started an investment account. | ### Doc VOI test documents When you're ready to begin testing, contact your Argyle Customer Success Manager to enable document permissions. Use the sample documents below for Doc VOI verifications. For all scenarios below, order a document verification with the following `employments` value: ```json theme={} "employments": [ { "employer": "Warehouse Services Inc", "status": "active", "hire_date": "2023-02-01", "termination_date": null } ] ``` Do not adjust file names. Upload the following documents: * Warehouse\_Services\_Inc\_paystub.pdf * Warehouse\_Services\_Inc\_paystub\_2025.pdf * Warehouse\_Services\_Inc\_paystub\_2024.pdf Upload the following documents: * Warehouse\_Services\_Inc\_paystub\_ineligible.pdf * Warehouse\_Services\_Inc\_paystub\_2025.pdf * Warehouse\_Services\_Inc\_paystub\_2024.pdf Upload only the following document: * Warehouse\_Services\_Inc\_paystub.pdf Production testing can be done with real documents. If needed, use the sample files below. Upload the following documents: * sandbox\_Warehouse\_Services\_Inc\_paystub.pdf * sandbox\_Warehouse\_Services\_Inc\_paystub\_2025.pdf * sandbox\_Warehouse\_Services\_Inc\_paystub\_2024.pdf Upload the following documents: * sandbox\_Warehouse\_Services\_Inc\_paystub\_ineligible.pdf * sandbox\_Warehouse\_Services\_Inc\_paystub\_2025.pdf * sandbox\_Warehouse\_Services\_Inc\_paystub\_2024.pdf Upload only the following document: * sandbox\_Warehouse\_Services\_Inc\_paystub.pdf