跳转到主要内容
本指南逐个调用地展示(含请求与响应)如何使用 Entities API 发送虚拟账户受益人的KYB要求中列出的信息。每一项在 Entities 中的位置见该页面的“如何发送”列。简而言之:公司是类型为 COMPANY 的实体,每个人是类型为 INDIVIDUAL 的实体(所有者作为 UBO 关联到公司),每份文件都是附带其文件的已声明文件。示例使用一家在巴西注册的虚构公司。

先决条件

流程

法定代表人。 将其创建为 INDIVIDUAL(其身份证明文件可作为主要文件),并通过关联 UBO 将其关联到公司:ownershipPercentage: 0 和 controlRole: LEGAL_REPRESENTATIVE。如果法定代表人同时也是所有者,则只需关联一次,使用其持股比例和 controlRole: LEGAL_REPRESENTATIVE。

分步操作

按以下顺序执行下列调用。保留 API 返回的每个 internalId 和 documentId。示例仅发送最少必需的内容。

  1. 阅读您的自定义字段架构

GET /api/entity/v1/custom-fields/schema 返回您的账户接受的属性。以下为包含业务概况的节选:

  1. 创建公司

POST /api/entity/v1/entities。税号为主要文件,业务概况放在 attributes 中:
Request
Response
响应为 201 Created(节选)。主要文件会返回其 documentId 且不含文件,这是预期行为:它不需要文件。

  1. 申报公司文件并上传文件

使用 POST /api/entity/v1/entities/{companyId}/documents 声明每份文件。公司注册文件在 id 中携带注册号(在巴西为 CNPJ):
然后针对每个文件发送一次 POST /api/entity/v1/documents/{documentId}/proofs,并设置 proofType=DOCUMENT 及该文件。响应(节选):
以同样的方式声明并上传资金来源文件,以及(对于 B2C)所有权证明:

  1. 创建每个人

每位所有者以及法定代表人各创建一个 INDIVIDUAL,使用 POST /api/entity/v1/entities。身份证明文件可作为主要文件:
Request
Response
响应为 201 Created(节选)。

  1. 上传每个人的身份证明文件

正反面都上传到同一份文件:先使用 proofType=FRONT 调用 POST /api/entity/v1/documents/{documentId}/proofs,再使用 proofType=BACK 调用(护照:仅 FRONT)。两次上传后 GET /api/entity/v1/documents/{documentId}/proofs 的节选:
每人调用一次 POST /api/entity/v1/entities/{companyId}/ubos。Jane Doe 持股 60%,同时也是法定代表人:
Request
Response
John Doe 持股 40%,角色使用大写:
GET /api/entity/v1/entities/{companyId}/ubos 会列出两者:
保留公司的 internalId:它在 Localpayment 中标识该受益人。

  1. 通知 Localpayment 上传已完成

当公司、其文件以及每位人员都已加载并关联后,对该公司调用 POST /api/entity/v1/entities/{companyId}/verify(请求验证)。它会通知 Localpayment 文档上传已完成。响应为 202 Accepted(节选):
当公司处于 IN_REVIEW 状态时会被锁定(409 ENTITY_IN_REVIEW)。调用 verify 后,您这部分的上传即告结束:之后无需轮询该实体的状态。

检查清单

  • 您申报的每份文件(公司注册文件、资金来源证明、身份证明文件)都有各自的存档。主要的税务识别文件无需存档。
  • 每位所有者都已通过其 ownershipPercentage 关联到公司,法定代表人则通过 controlRole: LEGAL_REPRESENTATIVE 关联。
  • 已在公司上设置 attributes.businessProfile。
  • 全部内容加载完成后,您已对公司调用了 verify。
  • 税务识别号码仅包含数字,且姓名与证件上的姓名完全一致。
  • 每个文件均为 PDF、PNG、JPG 或 JPEG 格式,且大小小于 10 MB。
核对清单完成后,Localpayment 会对公司和每位人员进行审核,并告知您是否需要进行任何更正。请参阅跟踪审核并修复拒绝问题。

下一步

跟踪审核并修复拒绝问题

根据审核结果,更正 Localpayment 要求的内容。

管理 UBO

更新或终止所有者链接。
最后修改于 2026年11月10日