Business Virtual Account (VA) Application Guide

Core Application Workflow ⚙️

The creation of a business Virtual Account focuses on the submission of account opening materials and the issuance of bank account details.

sequenceDiagram
    autonumber
    
    participant P as "Partner Platform"
    participant D as "DogPay"
    participant B as "Bank"

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

    Note over P, B: Phase: Legal Account Opening
    
    P->>D: 2. Upload business and personal VA files separately
    Note right of P: POST /open-api/v1/file/upload
    Note right of P: POST /open-api/v1/file/upload/va/legal-person
    D-->>P: Return fileIds for each document
    
    P->>D: 3. Request business VA creation
    Note right of P: POST /open-api/v1/va/legal-create-v2
    Note right of P: Must pass the fileIds in the attachments field
    D-->>P: 4. Information successfully submitted (Webhook)
    Note right of P: Event: va.create
    
    D->>B: Submit account opening instruction
    B-->>D: Bank issues Virtual Account
    D-->>P: 5. Account successfully created (Webhook)
    Note right of P: Event: va.update

Detailed Integration Steps 🚀

Step 1: Pre-check and Status Validation

1. Query Supported Banks (Optional): Call the Query Supported Banks endpoint to retrieve a list of partner banks currently available for business account opening.
2. Validate Entity Status: Before officially initiating the account opening, the system performs strict validation on the entity's admission status. You must confirm that the business entity satisfies the following core status condition to proceed:
   • kycStatus: "completed" (Business KYC review is fully approved)

Step 2: Upload VA Specific Files

In this phase, you must call the respective file upload endpoints to separately upload the required business and personal files for account opening, and retrieve the fileIds returned by the system.

• Business Files: Call the Upload File endpoint.
• Personal Files: Call the Upload Personal File endpoint.

Please strictly refer to the "Compliance Document Checklist" module below for the specific list of required files.

Step 3: Initiate VA Creation Request

Call the Request Business VA Creation (v2) endpoint to officially apply for bank account details.
When constructing the request payload, you must input all relevant file IDs obtained in Step 2 into the attachments array field for a unified submission.

Compliance Document Checklist 📋

When calling the upload endpoints, ensure that the fileUseType values strictly match the requirements below.

1. Required Business Documents for VA (All Countries/Regions)

When applying for a Virtual Account (VA) after the KYC review is approved, all businesses must provide the following 5 specific files:

2. Required Personnel Documents for VA (Personal Level)

In addition to business materials, key business personnel (such as Directors, UBOs) must also provide the following personal files for VA account opening:

Asynchronous Webhook Handling 🔔

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