Guides
英文/English中文/Chinese

企业账户（VA）入驻

企业实体验证、企业 KYC 提交和多方生物识别认证的分步说明。

📘

业务背景

此工作流专门用于为企业级子商户（Business Entities）开通虚拟账户 (Virtual Account)。与个人入驻不同，企业开户流程涉及企业资质文件的严格审查，以及多位相关核心人员（如董事 Directors、最终受益人 UBOs）的活体生物识别认证。

1. 核心开户工作流 (Workflow Overview)

sequenceDiagram
    autonumber
    
    participant U as 终端用户 (User)
    participant M as 商户系统 (Merchant)
    participant D as DogPay 支付网关
    participant C as 区块链网络 (Blockchain)

    Note over U, D: 阶段 1：订单创建与收银台展示
    U->>M: 1. 在商户侧发起结账请求
    
    M->>D: 2. [可选] 获取支持的币种与公链配置
    Note right of M: GET /open-api/v1/pay/currency-config
    
    M->>D: 3. 创建支付订单
    Note right of M: POST /open-api/v1/pay
    D-->>M: 返回订单详情及托管收银台链接 (payUrl)
    
    M->>U: 4. 向用户展示支付链接 (页面跳转/内嵌/二维码)
    
    Note over U, C: 阶段 2：用户支付与链上广播
    U->>C: 5. 用户通过 Web3 钱包扫描或调用合约完成转账
    
    Note over D, M: 阶段 3：链上监听与状态流转
    C-->>D: 6. 侦测到交易在内存池中 (Tx Unconfirmed)
    Note over D: 系统更新: waitAmountOnChain (等待确认金额) 增加
    
    D-->>M: 7. 订单状态更新通知 (Webhook)
    Note right of M: Event: pay.transaction.update
    
    C-->>D: 8. 交易所在区块达到安全确认数 (Tx Confirmed)
    Note over D: 系统更新: doneAmountOnChain 增加，订单状态变更为 completed
    
    D-->>M: 9. 支付最终完成通知 (Webhook)
    Note right of M: Event: pay.transaction
    
    M-->>U: 10. 商户后端放行/发货，并在前端展示成功页面
    
    Note over D, M: 阶段 4：资金清算 (Settlement)
    D->>D: 11. 资金结算入账至商户的加密货币钱包 (Crypto Wallet)

2. 详细对接步骤 (Integration Steps)

Step 1: 银行支持列表查询 (可选)

调用 GET /va/supported-banks 获取当前系统支持开户的合作银行列表。此接口无 KYC 限制，可随时调用。

Step 2: 实体创建与 KYC 文件提交

  • 首先调用 POST /entities/business 在 DogPay 系统中初始化该企业实体。
  • 随后调用 POST /entities/business-kyc 接口上传企业的合规审查文件。成功提交后，系统会在响应体中返回一个包含 person_id 的列表，指示哪些关联人员需要进行下一步的身份验证。

Step 3: 高管活体认证循环 (Biometric Authentication)

所有被系统指定的人员（通常为公司董事或最终受益人 UBO）都必须完成 Face ID 活体验证。

  • 针对每一个 person_id，调用 POST /entities/biometric-url 获取其专属的认证链接，并引导该人员完成操作。
  • 状态流转：当最后一名高管完成验证后，DogPay 会向您的系统发送 entity.status.update 的 Webhook 事件通知。

Step 4: 创建企业虚拟账户

在企业实体的 KYC 状态变更为通过（Approved）后，调用 POST /va/legal-create 正式为其开立企业级虚拟账户。

3. 企业 KYC 合规文件要求 (Required KYC Documents)

在执行 Step 2 提交文件时，请严格按照以下清单提供企业的合规材料。

📌 基础必传文件 (适用于所有地区)

字段名 (Field)文件说明
business_license营业执照 / 公司注册证书 (CI)
article_of_Incorporation公司章程
corporate_resolution公司决议
fatcaFATCA 表单
financial_statements财务报表
business_address_proof企业地址证明
source_of_funds资金来源证明

🇭🇰 香港地区企业专属要求

如果企业的注册地 (registrationRegion) 为 HK (香港)，除了上述基础文件外，还必须额外提供以下文件：

字段名 (Field)文件说明
nnc1法团成立表格 (NNC1)
nar1周年申报表 (NAR1) —— 仅限香港公司注册时间超过 1 年的需要提供
company_business_registration_certificate商业登记证 (BR)

4. Webhook 事件通知 (Webhook Events)

为了保证业务逻辑的闭环，请确保您的系统正确监听并处理以下事件：

事件键值 (Event Key)

触发条件 (Trigger Condition)

entity.status.update

  1. 当所有关联人员完成活体认证时触发；
  2. 当企业整体 KYC 资料被最终审核通过时触发。

va.create

当企业虚拟账户 (Business Virtual Account) 成功在底层银行开立并分配账号时触发。

⚠️

开发格式须知

由于当前上游清算渠道的技术限制，所有以图片形式上传的合规文件（如执照扫描件等），其文件格式必须为 JPEG（.jpg / .jpeg）。请在前端上传组件或后端处理逻辑中做好格式转换与校验，以免造成开户失败。

Updated 3 days ago