How to design a verification-first financial onboarding workflow using Docusign IAM and J.P. Morgan Payments

•

Summary•12 min read

Financial onboarding often breaks when verification and agreements happen in separate systems. This sample architecture shows how to verify identity and bank account details before generating an agreement with Docusign IAM and J.P. Morgan Payments.

Sample architecture: four stages for verification-first onboarding
How the sample workflow runs
Error handling: clean failures, not silent ones
Constraints and trade-offs
Key design decisions
The pattern is reusable
Where this pattern can help
Further reading

Prefer to watch? Niani Byrd, Developer Advocate at Docusign, recorded a walkthrough of this workflow. Watch the recording below, then read on for the deep dive.

In many financial onboarding workflows, verification and agreement generation happen in separate systems. Identity checks may run in one process, bank account validation in another, and agreement generation somewhere else.

Each handoff creates room for errors. Applicant data can be re-entered incorrectly, validation results can get separated from the agreement, and teams may not discover incomplete or inconsistent information until later in the process.

This post walks through a sample architecture for connecting those steps in one workflow. Using Docusign IAM, Workflow Builder, the Data I/O Extension, and J.P. Morgan Payments Validation Services, the workflow collects applicant data, verifies identity and bank account details, and generates an agreement only after the required checks pass.

Sample architecture: four stages for verification-first onboarding

In this example, a sample account-opening workflow uses Docusign and J.P. Morgan Payments components across four stages: data capture, orchestration, verification, and agreement generation/payment. Understanding the role of each layer is the starting point for adapting this pattern to your own systems.

Stage 1: Data capture with Docusign Web Forms

A Docusign Web Form is the entry point to the workflow. Fields are pre-configured with everything the downstream J.P. Morgan Payments calls need: name, SSN, address, date of birth, and account details. The form data maps directly into Workflow Builder's variable store, so the applicant enters information once and that structured data is routed to the right services at the right steps without any re-entry.

The workflow starts with machine-readable inputs rather than a scanned form that someone has to manually re-key.

Stage 2: Orchestration with Docusign Workflow Builder

Workflow Builder is the orchestration engine, with a visual editor where each node represents a configurable step and each arrow represents a routing decision. Teams can drag and drop steps, configure them through a form, and connect them with conditional logic, with no custom code, state machines, or webhooks required.

The conditional branching logic that traditionally lives deep in backend code now lives in the workflow definition itself. Authorized builders can review and update the workflow definition, save changes as a draft without affecting the published version in production, and duplicate live workflows to iterate without changing the extension app.

Stage 3: Verification via J.P. Morgan Payments Validation Services and the Data I/O Extension

Two J.P. Morgan Payments endpoints power the verification layer:

Entity Validation takes key information for an individual or organization, checks it against authoritative data sources, and returns a verified flag. This is the KYC layer: confirming the person is who they say they are before any account is opened.
Account Validation takes routing number, account number, and account holder details, and confirms the account exists and that ownership matches. This is the fraud prevention layer for funding and payment setup.

Both are POST requests that return structured JSON with a verified boolean in the response body. That flag is what Workflow Builder uses to branch the workflow downstream.

The services use a multi-provider data model, querying across J.P. Morgan and third-party sources to return a single, consolidated verification response. Personally identifiable information (PII) is not retained after a validation call completes—a key data protection feature built into the API by design.

The Data I/O Extension connects Workflow Builder to these external APIs. Architecturally, it's a thin, stateless adapter that takes structured input from Workflow Builder, maps it to J.P. Morgan's request schema, executes the API call, and returns the response. Workflow Builder owns the workflow state. J.P. Morgan Payments owns the verification logic. The extension handles the translation between them.

Stage 4: Agreement and payment

Only after both validation checks pass does Workflow Builder generate and route the agreement for eSignature. The Prepare Document Template step pulls in the J.P. Morgan Payments Account Opening Form and populates it with data the applicant already entered. The variable store handles it end-to-end. After signature, the next step could route validated, signed data into the appropriate payment or funding process, depending on the organization’s J.P. Morgan Payments integration.

This example focuses on agreement generation and verification; payment execution details will vary based on your own integration with J.P. Morgan Payments.

How the sample workflow runs

Here is how the full workflow runs for a high-yield savings account opening, including the decision logic at each stage.

Step 1: Trigger the workflow. The workflow is triggered via a shareable link. In a deployed version, this link could be embedded in an onboarding app or sent directly to the customer.

Step 2: Collect applicant data. The applicant completes the Web Form. All fields needed for both downstream J.P. Morgan Payments validation calls are captured in a single pass: name, SSN, address, date of birth, and account details. The data maps directly into Workflow Builder's variable store.

Step 3: Call Entity Validation. Once the form is submitted, Workflow Builder calls the Data I/O Extension, which calls J.P. Morgan's Entity Validation API. This confirms whether the individual or organization can be verified against multiple data sources. The response comes back into Workflow Builder as structured output variables, for example: Entity[1].Verified.

Step 4: Evaluate entity verification result. Workflow Builder evaluates the result. The branch condition reads Entity[1].Verified == true, with the ability to handle both boolean and integer responses from the API.

Pass: continue to Account Validation.
Fail: the applicant sees a verification incomplete screen and the workflow terminates cleanly on that branch. This is an intentional end state, not an unhandled error.

Step 5: Call Account Validation. If the entity is verified, Workflow Builder calls the Data I/O Extension again, this time routing to J.P. Morgan Payments Account Validation. Workflow Builder calls the extension, the extension calls J.P. Morgan, and the result comes back as a structured variable—for example, Account[1].Verified.

Step 6: Evaluate account verification result. Workflow Builder evaluates the account verification result using similar logic:

Both checks pass: proceed to document generation.
One fails: controlled off-ramp with a meaningful screen and a clean path end.

Step 7: Generate and send the agreement. When both verification checks pass, Workflow Builder generates the J.P. Morgan Payments Account Opening Form and populates it with data from the variable store. Every field is automatically populated from what the applicant entered in the Web Form. Workflow Builder then sends it for eSignature.

Step 8: Account opening confirmed. After signature, the applicant sees a confirmation screen. Data collection, identity verification, bank account validation, document generation, and eSignature ran as one workflow. The builder did not write orchestration logic, manage state between steps, build error handling for failed API calls, or code branch conditions. Workflow Builder handles all of that.

Behind that confirmation screen, two external API calls, two branch evaluations, and document generation ran inside a single unified runtime.

Error handling: clean failures, not silent ones

One of the less obvious design details in this workflow is how failure is handled. When the API returns an error (for example, a field exceeding maximum allowed length or a missing required property), a custom-built integration might surface it as an unhandled 400, or silently fail and leave the applicant stuck.

In this architecture, the false branch on Entity Verification handles it explicitly. Workflow Builder routes to a Show Confirmation Screen step on the failure path. The applicant sees a clear, intentional message rather than a broken experience.

Because the branching logic lives in the workflow definition rather than in code, updating the failure messaging or adding retry logic requires no deployment. You adjust the workflow configuration instead of modifying the extension or backend services.

Constraints and trade-offs

This pattern is useful, but it comes with trade-offs you should understand before adopting it.

Template field mapping must be exact. If a variable name from your Web Form doesn't exactly match the field reference in your agreement template, that field will silently remain blank in the generated agreement. Map form fields to template fields before building and test the full document generation path in QA.

Verification calls run sequentially, adding latency. Entity Validation and Account Validation execute in sequence: each call must complete before the next step fires. For most account opening use cases, this is acceptable. If your SLA requires sub-second responses, evaluate whether sequential verification fits your performance requirements, or whether you need to parallelize checks behind a separate service that emits a single boolean outcome to Workflow Builder.

Branch logic handles simple true/false conditions. The branching in this example evaluates a straightforward verified boolean. If your use case requires complex scoring, multi-factor routing, or blended results across providers, you’ll likely need a backend pre-processing step that normalizes results into a simple boolean (or small set of typed fields) before they reach Workflow Builder.

The verified field can return as a boolean or an integer. J.P. Morgan's Entity Validation API can return true/false or 1/0 depending on implementation version and environment. Your branch conditions must handle both. This is easy to miss when testing against a single environment.

J.P. Morgan Payments Validation Services access is required. You must confirm your organization’s access and onboarding status with J.P. Morgan Payments before building. The Data I/O Extension can be reconfigured to route to a different verification provider, but the API schemas, response structures, and branch conditions described here are specific to J.P. Morgan Payments Validation Services.

Key design decisions

A few architectural choices in this workflow are worth understanding explicitly, because they determine how you'd adapt this pattern to your own environment.

Verification gates execution. Workflow Builder uses the outcome of each validation call to determine whether the workflow continues. This prevents unvalidated data from flowing through to agreement generation, eliminating the class of NIGO errors that typically surface downstream.

The Data I/O Extension decouples orchestration from external services. Workflow Builder doesn't call J.P. Morgan's APIs directly. The Data I/O Extension handles routing, schema mapping, and response normalization. Orchestration and business logic live in the workflow and integration details live in the extension and external APIs. This keeps the orchestration logic clean and portable so you can extend or swap validation services without rewriting the workflow.

Structured data flows end-to-end through the variable store. Because the workflow starts with a structured Web Form, and because every step passes data through Workflow Builder's variable store, the signed agreement is generated from validated, machine-readable inputs. There is no re-entry, no copy-paste risk, and no data drift between what the applicant entered and what appears in the agreement.

Conditional logic lives in the workflow, not the backend. Branch conditions are defined in the workflow configuration, readable and modifiable by any builder without touching the extension app or the underlying API. The result is a workflow that's auditable, adaptable, and maintainable in a way that hard-coded backend logic is not.

The pattern is reusable

Account opening is one instance of a broader pattern that appears across financial workflows: don't execute the action until the agreement is in place and the underlying data is verified.

You’ll see the same sequence (validate → agree → activate) in investment account opening, loan application and disbursement, vendor onboarding with identity and payment setup, etc.

Once the pattern is built, it's extensible. Teams aren't rebuilding the same integration logic every time a new use case comes up. They adjust the Web Form, the validation calls, and the agreement template, while keeping the overall orchestration structure familiar.

Where this pattern can help

Financial onboarding workflows often break down when verification, agreements, and payments run as disconnected steps. A verification-first architecture changes that sequence: applicant data is collected once, validation checks run before agreement generation, and the workflow only proceeds when required identity and bank account checks pass.

The same sequence can apply beyond account opening: validate the data, generate the agreement, then activate the next step. For builders working on financial onboarding, payment authorization, vendor setup, or compliance recertification workflows, that pattern can help reduce manual handoffs and keep agreement execution tied to verified data.