Individual Entity Onboarding and KYC Guide

This guide explains how to create an individual entity and complete identity verification (KYC) through the API. Once verification is approved, continue with the Individual Virtual Account (VA) Application Guide.

📘

Business Context

Regulatory requirements oblige individual users to complete identity verification and provide proof of address before applying for a Virtual Account. This guide covers entity creation, authentication link issuance and verification result confirmation. It does not cover the VA application itself.


Core Verification Workflow ⚙️

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

    P->>D: 1. Create a person entity
    Note right of P: POST /open-api/v1/entities/person
    P->>D: 2. Create an entity auth URL
    Note right of P: POST /open-api/v1/entities/auth-url
    D-->>P: Return the authentication URL
    P->>U: 3. Forward the authentication URL
    U->>D: 4. Submit identity documents and complete liveness check in H5
    D-->>P: 5. Verification result notification (Webhook)
    Note right of P: Event: entity.status.update

Detailed Integration Steps 🚀

Step 1: Create the Person Entity

Call Create a person entity to create the individual sub-merchant record, and store the returned entity ID. Both the authentication link and the VA application require this entity.

Step 2: Create the Authentication Link

Call Create an entity auth URL and forward the returned URL to the user, who completes document upload and liveness verification in the H5 page.

The authentication link is valid for 1 hour. Once it expires the user cannot continue submitting; generate a new link by calling the endpoint again.

🏦

bank Is Required When Bank Account Capability Is Needed

When calling Create an entity auth URL, if the user will need bank account capability (Virtual Accounts), the businessTypes array must include bank.

This changes the verification flow itself: with bank, the verification page requires proof of address (address_proof) as part of the same session.

If bank was not selected during verification but bank account capability is needed later, the address-proof step is documented in the Individual Virtual Account (VA) Application Guide, not in this guide's verification flow.

Step 3: Confirm the Verification Result

Verification is asynchronous. Listen to the entity.status.update event and confirm kycStatus is completed before moving to the VA application stage.


Verification Documents 📋

fileUseTypeDescription
address_proofProof of residential address, for example a utility bill issued within 90 days
🚧

Address Proof Is Collected in the Verification Page

When businessTypes includes bank, the user uploads the address proof directly in the verification H5 page as part of that session. No separate upload call or submission is required.

Files must be in PDF, JSON, JPEG or PNG format.


Key Constraints 🚧

  • Entity creation and authentication links must use the same API credentials and the same entity.
  • businessTypes must include bank, otherwise the VA application will fail.
  • Authentication links are valid for 1 hour and must be regenerated after expiry; request one only when the user is ready to open it.
  • Verification is asynchronous; do not treat submission as completion.
  • Even after kycStatus is completed, confirm canApplyVa before applying for a VA.

Asynchronous Webhook Handling 🔔

Event KeyTrigger Logic
entity.status.updateTriggered when the user's KYC status changes (submitted, approved or rejected)

See Entity Status Events for payload details.


Did this page help you?