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.

KYC Submission Validation Rules 🛡️

Business Type and Registration Region Matching

businessType must use one of the allowed values below and must match the registration region:

Values such as public_limited_company, company, individual_businesses, trust, other, branch_office, and public_unlimited_company_with_share_capital are rejected.

18 Years of Age Validation

Signers and UBOs must be at least 18 years old on the submission date; turning 18 on the submission date is considered passing. resubmit-person performs the check when birthDate is provided, while add-person always validates it.

Prohibited Country Validation

Business KYC submission and resubmission validate all countries/regions related to the business and its personnel. If any country is configured with level prohibited in the risk_country_level dictionary, the system returns HTTP 400 with business code 1000300. The message includes the matched country codes (ISO-2, comma-separated when multiple). Empty fields are skipped, and country codes are trimmed and converted to uppercase before matching.

Fields No Longer Collected

registerCapital, taxStructure, taxCountries, and hasBearerShares are no longer collected. Passing these fields does not cause an error, but they have no effect. Integrators should not rely on receiving these values back after submission.

Company Size

The numberOfEmployees enum values remain unchanged: few (1-20 employees), normal (20-50 employees), and lot (50+ employees).

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 are determined by region, business type, and years of establishment. Please strictly upload files using the corresponding fileUseType dictionary values from the table below.

The share structure chart is uploaded with other and is required only when the business is not a sole proprietorship and no single shareholder holds 100% of the shares. The UK CS01 is uploaded with ANNUAL_AUDIT_FORM and is optional.

2. Required Personnel Documents (Personal)

Error Code Reference 🔍

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.