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 ContextRegulatory 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.
bankIs Required When Bank Account Capability Is NeededWhen calling Create an entity auth URL, if the user will need bank account capability (Virtual Accounts), the
businessTypesarray must includebank.This changes the verification flow itself: with
bank, the verification page requires proof of address (address_proof) as part of the same session.If
bankwas 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 📋
fileUseType | Description |
|---|---|
address_proof | Proof of residential address, for example a utility bill issued within 90 days |
Address Proof Is Collected in the Verification PageWhen
businessTypesincludesbank, 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.
businessTypesmust includebank, 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
kycStatusiscompleted, confirmcanApplyVabefore applying for a VA.
Asynchronous Webhook Handling 🔔
| Event Key | Trigger Logic |
|---|---|
entity.status.update | Triggered when the user's KYC status changes (submitted, approved or rejected) |
See Entity Status Events for payload details.
Updated less than a minute ago
