Individual Account (VA) Onboarding

[!info] Business Context This process is designed for Partners to apply for Virtual Bank Accounts (VAs) for their individual sub-merchants. The workflow is divided into two phases: Identity Verification (KYC) and Account Issuance.

1. Workflow Overview

The following sequence diagram illustrates the end-to-end interaction between the User, Partner, DogPay, and the Bank.

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

    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<br/>fileUseType=fatca
    P->>D: Submit Source of Funds documents (API)
    Note right of P: POST /open-api/v1/file/upload<br/>fileUseType=source_of_funds
    P->>D: Create a private VA (API)
    Note right of P: POST /open-api/v1/va/private-create
    
    D->>B: Submit account opening information
    B-->>D: Account opening completed
    D-->>P: Account opening completed (Webhook)
    Note right of P: Event: va.create
    
    P->>U: Notify user: Account ready

2. Integration Steps

Step 1: Identity Verification (KYC)

Depending on whether the user is new to the system, choose the appropriate API:

• New Users (Case 2): Call POST /entities/person to create the entity, then POST /entities/auth-url to get the hosted KYC link.
• Existing Users (Case 1): Only a Proof of Address (POA) is required via POST /entities/poa-url.

Step 2: Compliance Document Upload

Before applying for a VA, compliance documents must be uploaded:

• FATCA: Use /file/upload with fileUseType=fatca.
• Source of Funds (SOF): Use /file/upload with fileUseType=source_of_funds.

Step 3: Private VA Creation

Call POST /va/private-create to initiate the account opening request.

3. Webhook Events