Business Entity Onboarding and KYC Guide

Core Application Workflow ⚙️

The business entity onboarding certification consists of four main phases: entity creation, business file submission, status and personnel list query, and core personnel verification.

sequenceDiagram
    autonumber
    
    participant U as "Business User"
    participant P as "Partner Platform"
    participant D as "DogPay"

    Note over U, D: Business KYC Verification
    
    P->>D: 1. Create a business entity
    Note right of P: POST /open-api/v1/entities/business-v2
    
    P->>D: 2. Submit business KYC files
    Note right of P: POST /open-api/v1/entities/business-kyc-v2
    
    P->>D: 3. Query status and personnel list
    Note right of P: GET /open-api/v1/entities/business-kyc-info
    D-->>P: Return kycStatus and personId list

    loop For each required key person (Director/UBO)
        P->>D: 4. Get unique biometric URL
        Note right of P: POST /open-api/v1/entities/biometric-url
        D-->>P: Return the authentication URL
        P->>U: Forward the URL to the executive
        U->>D: 5. Visit URL, upload ID docs, and perform liveness check
        
        D-->>P: 6. Personnel biometric success (Webhook)
        Note right of P: Event: entity.person.biometric.success
    end

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

    Note over D, D: Final review by partner and compliance team
    D-->>P: 8. Business KYC completed (Webhook)
    Note right of P: Event: entity.status.update

Detailed Integration Steps 🚀

Step 1: Entity Creation

Call the Create Business Entity (v2) endpoint to initialize the secondary merchant's basic record in the system.

Step 2: Compliance Material Upload and KYC Submission

In this phase, you must upload various entity files to obtain fileId values before submitting the review request.

1. Business File Upload: Call the Upload File endpoint to obtain the fileId for business qualifications.
2. Pre-uploading Address Proof: The personnel objects (signer, ubos) contain a poaFileId field. You must call the upload file endpoint mentioned above in advance, specifying the fileUseType as address_proof to upload personal proof of address materials. Obtain the file ID and populate it into the respective person's poaFileId field.
3. KYC Submission: Call the Submit Business KYC (v2) endpoint, mapping all acquired file IDs and business information.

Step 3: Query Personnel List and Review Status

After submitting the business KYC, the system automatically generates a list of key personnel who require identity verification.

You can check the business personnel list returned by the endpoint at the end of Step 2, or call the Get business KYC information endpoint. This interface is not only used to actively pull the overall review status (kycStatus) of the business KYC, but more importantly, you can use this interface to obtain the personId list of core personnel and their respective current authentication status.

Step 4: Complete ID Upload and Biometric Authentication

Every key individual designated by the system must complete personal identity verification:

1. Obtain Link: For each personId retrieved in Step 3, call the Get Biometric URL endpoint and distribute the returned URL to the corresponding corporate personnel.
2. Submit ID and Liveness Check: After the business personnel open the authentication link in their browser, they will follow the on-screen instructions to upload their personal identification documents (such as passports, ID cards, driver's licenses, etc.) directly on that page, and complete the Face ID liveness check.
3. Status Monitoring: You can listen for the entity.person.biometric.success event to track individual progress in real-time. Once the final individual completes all verifications, the system will trigger the entity.status.update event.

Step 5: Exception and Rejection Handling

If the submitted KYC materials are non-compliant, the system will change the kycStatus to request.
In this scenario, please refer to the Business KYC Rejection and Resubmission Guide to retrieve rejection details and call the corresponding resubmission endpoints to update the materials.

Compliance Document Checklist 📋

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

1. Business Required Documents (By Country/Region)

The required qualification documents vary depending on the business's registration location. Please strictly upload files using the corresponding fileUseType dictionary values from the table below.

2. Required Personnel Documents (Personal)

Asynchronous Webhook Handling 🔔

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