Business Account (VA) Onboarding

📘

Business Context

This workflow is used to open Virtual Accounts for corporate sub-merchants. Unlike individual onboarding, this process involves strict corporate document review and biometric authentication (Face ID) for multiple key related persons (e.g., Directors or UBOs).

1. Workflow Overview

sequenceDiagram
    autonumber
    
    participant U as Corporate User
    participant P as Partner Platform
    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: Business KYC Verification
    
    P->>D: 1. Create a business entity
    Note right of P: POST /open-api/v1/entities/business
    
    P->>D: 2. Submit business KYC files
    Note right of P: POST /open-api/v1/entities/business-kyc
    D-->>P: Return person_ids for related individuals

    loop For each required key person
        P->>D: 3. Get biometric URL
        Note right of P: POST /open-api/v1/entities/biometric-url
        D-->>P: Return the unique biometric URL
        P->>U: Forward the URL to the executive
        U->>D: 4. Perform Face ID authentication
    end

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

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

    Note over U, B: Phase 2: Legal Account Opening
    
    P->>D: 7. Request corporate VA creation
    Note right of P: POST /open-api/v1/va/legal-create
    
    D->>B: Submit account opening instruction
    B-->>D: Bank issues Virtual Account
    D-->>P: 8. Account successfully created (Webhook)
    Note right of P: Event: va.create
    
    P->>U: Notify user: Account is ready

2. Integration Steps

Step 1: Supported Banks Pre-check (Optional)

Call GET /va/supported-banks to retrieve a list of currently supported banks for account opening. This endpoint has no KYC restrictions and can be called at any time.

Step 2: Entity Creation & Corporate KYC

• First, call POST /entities/business to initialize the corporate entity in the DogPay system.
• Next, call POST /entities/business-kyc to upload the corporate compliance documents. Upon successful submission, the response will include a list of person_ids, indicating which associated individuals need to proceed with identity verification.

Step 3: Biometric Authentication Loop

All designated key individuals (typically Directors or UBOs) must complete Face ID verification.

• For each person_id, call POST /entities/biometric-url to obtain their unique authentication link and guide them to complete the process.
• Status Update: Once the final executive completes verification, DogPay will trigger an entity.status.update webhook event to your system.

Step 4: Legal VA Creation

After the corporate entity's KYC status changes to Approved, call POST /va/legal-create to officially open a corporate-level Virtual Account for them.

3. Required KYC Documents

When submitting files in Step 2, please strictly provide the corporate compliance materials according to the following checklist.

📌 Base Required Documents (All Regions)

🇭🇰 Additional Requirements for Hong Kong Entities

If the entity's registrationRegion is HK (Hong Kong), the following documents must be provided in addition to the base requirements:

4. Webhook Events

To ensure a closed-loop business flow, please ensure your system correctly listens for and processes the following events:

⚠️

Developer Format Notice

Due to technical limitations of current upstream clearing channels, all compliance documents uploaded as images (e.g., scanned licenses) MUST be in JPEG (.jpg / .jpeg) format. Please ensure format conversion and validation are implemented in your frontend upload components or backend processing logic to prevent onboarding failures.