Unified Onboarding

2-3 hours

Unified Onboarding is a feature that orchestrates customer onboarding across Unit Banking and external payment processors through a single, coordinated flow. It creates a unified application that tracks the onboarding status across multiple systems, providing a seamless experience for customers who need to be onboarded to both Unit and payment processing services simultaneously.

What It Enables

• Single Application Flow: Create one unified application that automatically initiates onboarding in both Unit Banking and configured payment processors.
• Centralized Status Tracking: Monitor the onboarding progress across all systems through a single unified application status.
• Automated Document Management: Documents required by external systems are automatically tracked and synced.
• Event-Driven Synchronization: Status updates from external systems (via webhooks) automatically update the unified application status.
• Support for Business and Sole Proprietor Customers: Full support for both business entities and sole proprietors.

When to Use

Use Unified Onboarding when:

1. Your customers need access to both Unit Banking services AND payment processing capabilities.
2. You want to provide a streamlined onboarding experience without requiring separate application flows.
3. You need centralized visibility into onboarding progress across multiple financial service providers.

Application Types

Unified Onboarding supports two customer types:

Type	Resource Type	Use Case
Business	businessUnifiedApplication	LLCs, Corporations, and Partnerships
Sole Proprietor	solePropUnifiedApplication	Individual business owners operating as sole proprietors

Application Status Lifecycle

Unified Application Statuses

Status	Description
Pending	Application created, initial processing not yet started
AwaitingDocuments	One or more child applications require document uploads
AwaitingIdentityVerification	The payment processor requires additional identity verification
Submitted	Application submitted for review
InReview	Documents or application under review by external systems
Approved	All child applications approved
PartiallyApproved	Some child applications approved, others pending/rejected
Rejected	Application rejected by one or more systems
Cancelled	Application cancelled
Error	Error occurred during processing

Child Application Statuses

Each child application (Unit, payment processor) has its own status that contributes to the overall unified status:

Status	Description
Pending	Child application created, awaiting processing
AwaitingDocuments	Documents required or previously submitted documents were invalid
AwaitingIdentityVerification	Identity verification required by the payment processor
InReview	Documents pending review by the external system
Approved	Child application approved
Rejected	Child application rejected

Payment Processor Settings Configuration

To enable Unified Onboarding with payment processors, you must configure the payment processor settings in your organization's settings.

Configuring Payment Processor Settings

Payment processor settings are configured through the Unit Dashboard.

To configure your payment processor settings:

1. Navigate to Settings from the top menu under the Developer section.
2. Select the Payment Processing tab.
3. Select your Vendor from the dropdown (e.g., Stripe).
4. Enter your Secret/Restricted API key (your payment processor secret key).
5. Enter your Publishable API key.
6. Enter your Webhook secret (your payment processor webhook signing secret).
7. Select the applicable Business profile MCC code for your use case.
8. Optionally, configure Hostname and Files Hostname for custom configurations.
9. Click Save to apply your settings.

Required Settings

Setting	Required	Description
Vendor	Yes	Select your payment processor (e.g., Stripe).
Secret/Restricted API key	Yes	Your payment processor API key (secret key). This is required for Unit to create and manage accounts on your behalf.
Publishable API key	Yes	Your payment processor publishable API key.
Webhook secret	Yes	Your payment processor webhook signing secret. This is required to verify incoming webhook events and keep application status synchronized.
Business profile MCC code	Yes	The Merchant Category Code for card transactions.
Hostname	No	Custom API hostname (for testing or custom configurations). Defaults to the payment processor's production API.
Files Hostname	No	Custom hostname for file uploads.

Supported Payment Processors

Currently, the following payment processors are supported:

Processor	Type Code	Description
Stripe	r	Stripe Connect for payment processing

Additional payment processors will be added based on partner request.

How Payment Processor Integration Works

1. Application Creation: When a unified application is created through the application form, Unit automatically creates an account with the configured payment processor.
2. Status Synchronization: Payment processor webhook events update the child application status in real-time.
3. Document Requirements: When the payment processor requires identity verification documents, the child application status changes to AwaitingDocuments.
4. Verification Flow: Documents can be uploaded through the unified onboarding document upload flow.
5. Identity Verification: In certain cases, the payment processor may require additional identity verification. When this happens, the child application status changes to AwaitingIdentityVerification, and the end customer is presented with an embedded session to complete the verification directly within the onboarding flow.

Stripe Identity Verification Flow

During Unified Onboarding, Stripe may determine that additional identity verification is required for a connected account. When this happens, Unit integrates with Stripe Identity to provide an in-line verification experience within the onboarding flow.

When Identity Verification Is Triggered

Stripe determines whether identity verification is needed based on its own risk assessment and compliance requirements. When required, Stripe sets the additional_verifications.document.status field on the connected account to unverified. Unit detects this status change through the account.updated webhook event and transitions the payment processor child application to AwaitingIdentityVerification.

How It Works

1. Detection: Unit receives an account.updated Stripe webhook indicating that additional_verifications.document.status is unverified.
2. Status Update: The payment processor child application status changes to AwaitingIdentityVerification, which propagates to the unified application status.
3. Verification Session: Unit creates a Stripe Identity verification session using the configured Stripe API keys. The end customer is presented with an embedded verification component to complete the identity verification (e.g., ID document upload and selfie capture).
4. Completion: Once the customer completes the verification and Stripe confirms the result, Unit receives an account.updated webhook with additional_verifications.document.status set to verified.
5. Approval: If identity verification is the last remaining requirement (besides external account setup, which is handled post-banking-approval), the child application status transitions to Approved.

Status Priority

The AwaitingIdentityVerification status has specific priority behavior in the status derivation:

• Child application level: AwaitingIdentityVerification takes the highest priority — regardless of document verification status, if Stripe requires identity verification, the child application will show AwaitingIdentityVerification.
• Unified application level: AwaitingIdentityVerification is evaluated after AwaitingDocuments. If any child application is awaiting documents, the unified status will be AwaitingDocuments. Otherwise, if any child is awaiting identity verification, the unified status will be AwaitingIdentityVerification.

Note

Identity verification is determined by Stripe and may not be required for all accounts. The AwaitingIdentityVerification status only appears when Stripe explicitly requests additional identity verification for the connected account.

Pre-Filling Payment Processor Information

When creating an application form for Unified Onboarding, you can use the ApplicationFormPrefill to indicate whether the end customer already has an existing payment processor account. This is useful when your platform has already onboarded users onto a payment processor and you want to streamline the unified onboarding flow by linking the existing account rather than creating a new one.

Two optional fields are available in the applicantDetails prefill:

hasPaymentProcessorAccount

boolean

Indicates whether the applicant already has an account with a payment processor. When set to true, Unit will attempt to link the existing account instead of creating a new one.

paymentProcessorAccountId

string

The ID of the applicant's existing payment processor account (e.g., a Stripe connected account ID). Should be provided when hasPaymentProcessorAccount is true.

By providing these fields, you can:

• Reduce onboarding friction for end customers who are already set up with a payment processor, avoiding duplicate account creation.
• Maintain continuity by linking the customer's existing payment processor account to their new Unit banking account.
• Streamline the unified flow so that the onboarding process focuses only on the Unit Banking setup while automatically associating the existing payment processor account.

Unified Onboarding Webhook Events

To receive notifications about unified application status changes, configure a webhook endpoint in your organization settings. Unit will send webhook events when unified applications reach terminal or significant states.

Available Unified Onboarding Webhook Events

Event Type	Description
unifiedApplication.created	Fired when a new unified application is created
unifiedApplication.approved	Fired when all child applications are approved and the unified application reaches Approved status
unifiedApplication.rejected	Fired when the unified application is rejected
unifiedApplication.partiallyApproved	Fired when some child applications are approved but others are pending or rejected

To receive these events, ensure your organization has a webhook endpoint configured that subscribes to unified application events. This allows your system to:

• Trigger downstream processes when onboarding completes successfully
• Notify internal teams when applications require attention
• Update your own systems with the latest application status
• Handle partial approvals where only some systems approved the application

Event Payloads

unifiedApplication.created

Fired when a new unified application is created.

{
  "data": [
    {
      "id": "12345678",
      "type": "unifiedApplication.created",
      "attributes": {
        "userIds": ["user-abc123"],
        "createdAt": "2026-01-15T10:30:00.000Z",
        "childApplications": [
          {
            "id": "1234567",
            "type": "Unit",
            "status": "Pending"
          },
          {
            "id": "acct_1ABCDefGHIJKLMNO",
            "type": "PaymentProcessor",
            "status": "Pending"
          }
        ]
      }
    }
  ]
}

unifiedApplication.approved

Fired when all child applications are approved.

{
  "data": [
    {
      "id": "12345679",
      "type": "unifiedApplication.approved",
      "attributes": {
        "userIds": ["user-abc123"],
        "createdAt": "2026-01-15T11:00:00.000Z",
        "childApplications": [
          {
            "id": "acct_1ABCDefGHIJKLMNO",
            "type": "PaymentProcessor",
            "status": "Approved"
          },
          {
            "id": "1234567",
            "type": "Unit",
            "status": "Approved"
          }
        ]
      }
    }
  ]
}

unifiedApplication.partiallyApproved

Fired when some child applications are approved but others are pending or rejected.

{
  "data": [
    {
      "id": "12345680",
      "type": "unifiedApplication.partiallyApproved",
      "attributes": {
        "userIds": ["user-abc123"],
        "createdAt": "2026-01-15T11:30:00.000Z",
        "childApplications": [
          {
            "id": "acct_1ABCDefGHIJKLMNO",
            "type": "PaymentProcessor",
            "status": "Approved"
          },
          {
            "id": "1234567",
            "type": "Unit",
            "status": "Rejected"
          }
        ]
      }
    }
  ]
}

unifiedApplication.rejected

Fired when the unified application is rejected.

{
  "data": [
    {
      "id": "12345681",
      "type": "unifiedApplication.rejected",
      "attributes": {
        "userIds": ["user-abc123"],
        "createdAt": "2026-01-15T12:00:00.000Z",
        "childApplications": [
          {
            "id": "acct_1ABCDefGHIJKLMNO",
            "type": "PaymentProcessor",
            "status": "Rejected"
          },
          {
            "id": "1234567",
            "type": "Unit",
            "status": "Rejected"
          }
        ]
      }
    }
  ]
}

Stripe API Key Permissions

If you are using a Stripe secret key, all permissions are granted by default. If you are using a Stripe restricted API key (recommended for production), the following permissions must be enabled:

For more information about Stripe permissions, see the Stripe Permissions Reference.

Creating a Restricted API Key

1. Navigate to Developers → API keys in your Stripe Dashboard.
2. Click Create restricted key.
3. Give your key a name (e.g., "Unit Unified Onboarding").
4. Set the following permissions:

Required Permissions

Resource Category	Resource	Permission Level
Connect	Accounts	Write
Connect	Persons	Write
Core	Files	Write
Identity	Verification Sessions and Reports	Write

5. Click Create key and copy the restricted key to configure in your Unit payment processor settings.

Why These Permissions Are Needed

Permission	Purpose
Accounts (Write)	Create and update Stripe Connect accounts, retrieve account status and requirements, and set external bank accounts after Unit Banking approval.
Persons (Write)	Create and update persons (representatives and beneficial owners) on Connect accounts, and attach verification documents.
Files (Write)	Upload identity verification document files to Stripe.
Verification Sessions and Reports (Write)	Create and manage Stripe Identity verification sessions for identity verification during onboarding.

Note: Write access in Stripe implicitly includes Read access, so enabling Write for Accounts, Persons, Files, and Verification Sessions and Reports covers all operations in the unified onboarding flow.

Required Stripe Webhook Events

The following Stripe webhook events must be enabled in your Stripe Dashboard (or via API) for the unified onboarding flow to function correctly. These events are used to synchronize the payment processor child application status in real-time.

Events Required for Unified Onboarding

Stripe Event Type	Purpose	Unified Onboarding Action
account.updated	Fired when account requirements or status change	Updates child application status based on current account requirements (e.g., pending verification, approved, has errors)
account.application.authorized	Fired when the Connect application is authorized	Initializes the payment processor child application with Pending status
person.created	Fired when a new person is added to an account	Evaluates person verification status and creates document requirements if needed
person.updated	Fired when a person's details or verification status change	Updates document status based on verification state: Unverified → document required, Pending → document pending review, Verified → document approved
person.deleted	Fired when a person is removed from an account	Evaluates impact on child application verification status
identity.verification_session.created	Fired when an identity verification session is created	Logged for audit purposes
identity.verification_session.processing	Fired when a verification session begins processing	Logged for audit purposes
identity.verification_session.verified	Fired when an identity verification session is successfully verified	Logged for audit purposes
identity.verification_session.requires_input	Fired when a verification session requires additional input from the user	Logged for audit purposes
identity.verification_session.canceled	Fired when a verification session is canceled	Logged for audit purposes
identity.verification_session.redacted	Fired when a verification session's collected data is redacted	Logged for audit purposes

Configuring Webhook Events in Stripe

1. Navigate to Developers → Webhooks in your Stripe Dashboard.
2. Click Add endpoint and enter the webhook URL provided by Unit.
3. Under Events to send, select the events listed in the table above.
4. Copy the Signing secret and configure it as the Webhook secret in your Unit payment processor settings.