VA Application Rejection and Resubmission Guide

Core Interaction Sequence Diagram 📊

The following sequence diagram illustrates the end-to-end interaction flow, starting from receiving the rejection webhook, querying tasks, processing user resubmission, and finally proceeding to the normal account opening approval and issuance:

sequenceDiagram
    autonumber
    actor User as User
    participant Partner as Partner
    participant DogPay as DogPay
    participant Bank as Bank

    Note over Partner, DogPay: 1. Rejection Trigger & Query
    DogPay->>Partner: Webhook: entity.status.update (status=pending_attachment)
    Partner->>DogPay: Call GET /va/rejection-records to fetch rejection details
    DogPay-->>Partner: Return structured tasks (with fileUseType, rejectionRecordId)
    Partner->>User: Notify user to supplement/re-submit specific rejected materials
    User-->>Partner: User submits new materials to Partner

    Note over Partner, DogPay: 2. Re-upload & Resubmit
    Partner->>DogPay: Route to specific upload API based on bizType
    DogPay-->>Partner: Return new fileId(s)
    Partner->>DogPay: Call POST /va/resubmit-attachment to submit files
    DogPay-->>Partner: Resubmission successful (Triggers pending_review upon full completion)
    DogPay->>Partner: Webhook: entity.status.update (status=pending_review)

    Note over Partner, Bank: 3. Normal Account Opening Flow Resumes
    DogPay->>DogPay: Admin approves the application (applying)
    DogPay->>Partner: Webhook: va.create (Information successfully submitted)
    DogPay->>Bank: Submit account opening instruction to the underlying bank
    Bank-->>DogPay: Bank issues Virtual Account
    DogPay->>Partner: Webhook: va.update (Account successfully created)
    Partner->>User: Notify user: Account ready

Standard Workflow for Resubmission ⚙️

Handling VA rejection resubmissions requires strictly following these four standardized steps:

Step 1: Receive the Rejection Webhook
When an application is rejected, the system triggers the entity.status.update webhook. The payload's status will change to pending_attachment, and it will include the specific vaAccountId along with a structured rejection object containing a batchId and task details.

Step 2: Query Specific Rejection Records
Call the new Get VA rejection records endpoint, passing the vaId to retrieve the detailed task list (this can also be found via GET va/detail). The returned records explicitly indicate which files were rejected (fileUseType) and provide the unique rejectionRecordId required for submission.

Step 3: Upload New Files Based on Business Type
Before submitting the resubmission, you must upload the new files to obtain new fileIds. The upload endpoint routing strictly depends on the bizType field found in the task record:

Step 4: Invoke the API to Complete Resubmission
Once you have the fileIds for the new files, call the new Resubmit VA attachment endpoint to perform a precise replacement.
You can submit tasks individually or batch-submit multiple pending tasks at once. When all pending tasks for the current cycle transition to done, the VA order status automatically upgrades to pending_review and re-enters the manual approval queue.

Core Constraints and Common Pitfalls 🚧

Please ensure the following strict rules are validated during integration to avoid resubmission rejections:

• Mandatory File Count Alignment: The number of fileIds passed in the items[].fileIds array must exactly match the number of files listed in the task's snapshot (snapshot.rejectedAttachments).
• Consistent File Use Type: If the rejected file was a CORPORATE_RESOLUTION, the fileUseType used when uploading the new file to clear the task must identically be CORPORATE_RESOLUTION.
• Personnel Isolation Limits: For personnel attachments (VA_LEGAL_PERSON_ATTACHMENT), the newly uploaded files must strictly belong to the targetId (i.e., the personId) specified in the pending task. Corporate-level and private VA attachments must use the account-level upload API without a personId.
• Status Prerequisite: The VA order must be in the pending_attachment status to permit resubmissions.
• Handling Obsolete Records: If a VA goes through multiple rejection cycles, uncompleted tasks from the previous cycle automatically change to canceled status. You must never attempt to use these done or canceled rejectionRecordIds again.
• Unreplaceable File Scope: Biometric reports (from facial recognition) and KYC IDs (Passports/ID cards) are not covered by this resubmission endpoint; replaceable personnel attachments are strictly limited to FATCA and Source of Funds. Attachments not listed in the pending tasks do not need to be re-uploaded.

Typical Scenarios 💡