Business Account (VA) Onboarding

📘

Business Context

This workflow is specifically used for opening Virtual Accounts for business sub-merchants. Unlike individual onboarding, the business process involves a thorough review of company credentials and identity verification for multiple key related persons, such as Directors or Ultimate Beneficial Owners (UBOs). Associated personnel must also submit personal compliance documents in addition to completing biometric authentication.

Core Application Workflow ⚙️

The business Virtual Account opening process is divided into two phases: Compliance Verification and Account Creation.

sequenceDiagram
    autonumber
    
    participant U as "Business 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 (Director/UBO)
        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
        
        D-->>P: 5. Personnel biometric authentication successful (Webhook)
        Note right of P: Event: entity.person.biometric.success
        
        P->>D: 6. Upload personal FATCA and source of funds files
        Note right of P: POST /open-api/v1/file/upload/va/legal-person
    end

    D-->>P: 7. 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: 8. Business KYC completed (Webhook)
    Note right of P: Event: entity.status.update

    Note over U, B: Phase 2: Legal Account Opening
    
    P->>D: 9. Request business VA creation
    Note right of P: POST /open-api/v1/va/legal-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 is 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 business account opening. This endpoint has no KYC restrictions and can be used for frontend display at any time.

Step 2: Entity Creation and KYC File Submission

1. First, call the Create Business Entity endpoint to initialize the secondary merchant record in the system.
2. Uploading compliance materials and KYC submission flow:
   • Business File Upload: Call the Upload File endpoint to obtain the unique fileId returned by the system.
   • KYC Submission: Call the Submit Business KYC endpoint, mapping the acquired fileId values to their respective fields.

❗

Critical Dependency

The unique person_id used for subsequent executive authentication is only issued by the system after successfully submitting the business KYC request via this interface.

Step 3: Biometric Authentication and Personal File Upload

Every key individual designated by the system must complete a dual verification process:

1. Biometric Authentication: For each person_id, call the Get Biometric URL endpoint to obtain a unique link and guide the individual to complete Face ID verification.
2. Personal File Submission: Call the Upload Personal File endpoint to submit the required materials (fatca and source_of_funds) for each person_id.
3. Status Monitoring: You can listen for the entity.person.biometric.success event to track progress in real-time. Once the final individual completes all verifications, the system will trigger the entity.status.update event.

Step 4: Legal VA Creation

Before officially initiating business Virtual Account creation, the system performs strict validation on the entity's admission status. Partners must verify via the interface that the business entity simultaneously satisfies the following two core status conditions:

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

Once both conditions are met, call the Request Business VA Creation endpoint to officially apply for bank account details.

Compliance Document Checklist 📋

When calling upload endpoints, ensure that the fileUseType values strictly match the following enums.

🚧

Document Upload Technical Specifications

Format Restrictions

Due to current upstream clearing channel limitations, all compliance documents (both business and personal) uploaded as images must currently be in JPEG (.jpg / .jpeg) format. Future updates may support additional formats; please refer to the live documentation for updates.

Submission Paths: Use the business Upload File endpoint for company documents, and the Upload Personal File endpoint for personnel documents.

1. Base Required Documents (Business)

2. Required Personnel Documents (Personal)

3. Additional Requirements for Hong Kong (HK) Entities

If the registration region is HK, you must also upload: nnc1 (Incorporation Form), nar1 (Annual Return), and company_business_registration_certificate (Business Registration Certificate).

Asynchronous Webhook Handling 🔔

Since BAAS core processes are executed asynchronously, please ensure your system correctly handles the following Webhook events to drive the business loop.

Core Event List

Detailed Event Reference

• Entity Status Event Details
• Personnel Authentication Event Details
• Virtual Account Event Details