Individual Account (VA) Onboarding

📘

Business Context

This workflow is specifically designed for Partners to apply for Virtual Accounts for individual users. According to regulatory requirements, all individual users must complete identity verification and submit relevant compliance documents to satisfy bank due diligence before an account can be opened.

Core Application Workflow ⚙️

The opening of an individual Virtual Account involves coordination between the User, the Partner, DogPay, and the partner Bank.

sequenceDiagram
    autonumber
    
    participant U as "User"
    participant P as "Partner"
    participant D as "DogPay"
    participant B as "Bank"

    Note over P, D: Optional: Pre-check
    P->>D: Query supported banks
    Note right of P: GET /open-api/v1/va/supported-banks

    Note over U, B: Phase 1: KYC Verification
    
    alt Case 1: Historical KYC User (Address Verification)
        P->>D: Create a POA URL for an authorized entity (API)
        Note right of P: POST /open-api/v1/entities/poa-url
        D-->>P: Return the POA URL
        P->>U: Forward the POA URL
        U->>D: Submit POA information (via URL)
    else Case 2: New User (Full KYC)
        P->>D: Create a Person entity (API)
        Note right of P: POST /open-api/v1/entities/person
        P->>D: Create an entity auth URL (API)
        Note right of P: POST /open-api/v1/entities/auth-url
        D-->>P: Return the KYC URL
        P->>U: Forward the KYC URL
        U->>D: Submit KYC information (via URL)
    end

    Note over D, B: Unified Backend Processing
    D->>B: Submit KYC information
    B-->>D: KYC completed
    D-->>P: KYC completed (Webhook)
    Note right of P: Event: entity.status.update

    Note over U, B: Phase 2: Account Opening
    
    U->>P: Submit account opening materials
    P->>D: Submit FATCA documents (API)
    Note right of P: POST /open-api/v1/file/upload?fileUseType=fatca
    P->>D: Submit Source of Funds documents (API)
    Note right of P: POST /open-api/v1/file/upload?fileUseType=source_of_funds
    P->>D: Create a private VA (API)
    Note right of P: POST /open-api/v1/va/private-create
    D-->>P: 10.Information successfully submited (Webhook)
    Note right of P: Event: va.create
    
    D->>B: Submit account opening instruction
    B-->>D: Bank issues Virtual Account
    D-->>P: 11. Account successfully created (Webhook)
    Note right of P: Event: va.update
    
    P->>U: Notify user: Account ready

Detailed Integration Steps 🚀

Step 1: Supported Banks Pre-check (Optional)

Partners can call the Query Supported Banks endpoint to retrieve a list of partner banks currently available for individual account opening. This endpoint is commonly used for frontend display to let users choose their preferred bank.

Step 2: Identity Verification (KYC)

Choose the appropriate verification method based on the user's history in the system:

• New Users: Call the Create a person entity interface first, then use Create a entity auth url to guide the user to complete identity verification on the H5 page.
• Existing Users: If the user has completed basic verification, only Proof of Address is required via Create POA url for a authorized private entity.

❗

Business Type Parameter Validation

When calling the Create a entity auth url interface to obtain the authentication link, if the user intends to use BAAS services (Virtual Accounts), the businessTypes array in the request body must include the "bank" field. Failure to include this field will prevent the entity from passing the bank's pre-onboarding validation.

Step 3: Compliance Document Upload

Necessary compliance materials must be submitted before officially initiating the account opening request.

• Call the Upload file interface to obtain the fileId for both the FATCA and Source of Funds documents.
• Critical Note: Requests without these documents will be intercepted by the system.

Step 4: Individual Virtual Account Issuance

Before officially initiating individual Virtual Account creation, the system performs pre-onboarding entry validation on the entity's status. Partners must verify via the interface that the individual entity simultaneously satisfies the following two core status conditions:

• kycStatus: "completed" (Individual KYC verification is fully completed)
• canApplyVa: true (The entity is qualified for account opening)

Once both conditions are met, call the Create private VA interface to initiate the final account opening instruction.

Compliance Document Checklist 📋

Ensure that the fileUseType values strictly match the following enums when calling upload interfaces.

🚧

Document Upload Technical Specifications

Format Restrictions

Due to current upstream clearing channel limitations, all compliance documents uploaded as images must currently be in JPEG (.jpg / .jpeg) format.

Submission Path: For individual users, please use the Upload file interface uniformly for all documents.

Asynchronous Webhook Handling 🔔

The individual onboarding process involves asynchronous bank review. Ensure your system correctly handles the following events to drive the business loop.

Core Event List

Detailed Event Reference

• Entity Status Event Details
• Virtual Account Event Details