Business Account (VA) Onboarding

[!info] Business Context This workflow is used to open Virtual Accounts for corporate sub-merchants. Unlike individual onboarding, this process involves corporate document review and biometric authentication for multiple related persons (Directors/UBOs).

1. Workflow Overview

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 (API)
    Note right of P: GET /open-api/v1/va/supported-banks

    Note over U, B: Phase 1: Business KYC Verification
    
    P->>D: Create a business entity (API)
    Note right of P: POST /open-api/v1/entities/business
    
    P->>D: Submit business KYC files (API)
    Note right of P: POST /open-api/v1/entities/business-kyc
    D-->>P: Return person_ids for related individuals

    loop For each required person
        P->>D: Get biometric URL (API)
        Note right of P: POST /open-api/v1/entities/biometric-url
        D-->>P: Return the biometric URL
        P->>U: Forward the URL
        U->>D: Perform biometric authentication (Face ID)
    end

    D-->>P: All persons authenticated (Webhook)
    Note right of P: Event: entity.status.update

    Note over D, B: DogPay & Bank Review Process
    D->>B: Submit business KYC for bank approval
    B-->>D: KYC approved
    D-->>P: Business KYC completed (Webhook)
    Note right of P: Event: entity.status.update

    Note over U, B: Phase 2: Legal Account Opening
    
    P->>D: Create a legal VA (API)
    Note right of P: POST /open-api/v1/va/legal-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: Pre-check (Optional)

Use GET /va/supported-banks to retrieve a list of currently supported banks. This can be called at any time without KYC restrictions.

Step 2: Entity Creation & Corporate KYC

• Call POST /entities/business to initialize the corporate entity.
• Call POST /entities/business-kyc to upload corporate documents. The response will include a list of person_ids for required individuals.

Step 3: Biometric Authentication Loop

All designated individuals (Directors/UBOs) must complete Face ID verification.

• Call POST /entities/biometric-url for each person_id.
• Webhook Status: Once the last person completes verification, you will receive an entity.status.update notification.

Step 4: Legal VA Creation

After all KYC reviews are passed, call POST /va/legal-create to open the corporate account.

3. Webhook Events