跳转到主要内容
POST
注册自然人(INDIVIDUAL)或法人实体(COMPANY)及其身份证明文件。实体将以 PENDING_KYC 状态创建,且不含文件;之后请通过“上传证明”上传支持文件。
  • 创建时会验证最低 KYC 数据:INDIVIDUAL 需提供 name 和 lastname,COMPANY 需提供 name。否则 API 将返回 422 INCOMPLETE_KYC_DATA。
  • 未知属性将被拒绝,并返回 400 VALIDATION_ERROR。任何额外数据请放入 attributes。
  • 国家/地区代码必须为 ISO 3166-1 alpha-3 格式(BRA,而不是 BR)。
  • 税务 ID(CPF、CNPJ、CUIT、RFC 等)是一种文件,而不是实体的字段。请在 document 中发送;创建时不接受 documents[](400 VALIDATION_ERROR)。
  • 其他文件(身份证件、地址证明、公司章程)请通过“添加文件”添加。
  • 请保留响应中的 document.documentId:它是用于向主文件上传文件的 docId。
错误使用带有固定 code 的 application/problem+json。完整目录:实体状态和错误代码。

授权

Authorization
string
header
必填

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

请求头

Authorization
string
必填

用于身份验证的 Bearer 访问令牌。该令牌可从获取访问令牌或刷新访问令牌endpoint 获取。系统将据此识别您的商户账户和执行操作的用户。

示例:

"Bearer <your_access_token>"

X-Correlation-ID
string

跟踪标识符(UUID)。会在响应中原样返回;如未提供,则由 Localpayment 生成。

示例:

"0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10"

请求体

application/json
externalId
string
必填

您为该实体提供的专属标识符。每个商户的标识符必须唯一,长度为 1 至 64 个字符。

示例:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

type
enum<string>
必填

INDIVIDUAL(自然人)或 COMPANY(法人实体)。

可用选项:
INDIVIDUAL,
COMPANY
示例:

"COMPANY"

name
string
必填

名字(INDIVIDUAL)或法定名称(COMPANY)。最多 255 个字符。

示例:

"Example Company S.A."

document
object
必填

实体的身份证明文档(税号或身份证件)。它将成为主要文档。其他文档随后通过“添加文档”添加。

lastname
string

姓氏。个人必填。最多 255 个字符。

示例:

"Doe"

birthdate
string<date>

YYYY-MM-DD。建议用于 INDIVIDUAL。

示例:

"1990-01-15"

gender
enum<string>

MALE、FEMALE、OTHER 或 UNDISCLOSED。

可用选项:
MALE,
FEMALE,
OTHER,
UNDISCLOSED
示例:

"FEMALE"

nationality
string

ISO 3166-1 alpha-3(BRA、ARG、MEX)。

示例:

"BRA"

birthCountry
string

ISO 3166-1 alpha-3。

示例:

"BRA"

residenceCountry
string

ISO 3166-1 alpha-3。对于 COMPANY,为税务居住国。

示例:

"BRA"

occupation
string

职业。最多100个字符。

示例:

"Engineer"

isPep
boolean

政治公众人物。默认值为 false。

示例:

false

incorporationDate
string<date>

YYYY-MM-DD。仅限 COMPANY。

示例:

"2020-01-15"

incorporationCountry
string

ISO 3166-1 alpha-3。仅限 COMPANY。

示例:

"BRA"

website
string

公司网站。最多 255 个字符。

示例:

"https://www.example.com"

法定代表人(公司)名称。最多 255 个字符。

示例:

"Jane Doe"

email
string

联系邮箱。最多 255 个字符。

示例:

"test@example.com"

phone
object

联系电话,每部分仅输入数字。

address
object

邮寄地址。提供时必须填写国家/地区。

attributes
object

由您的自定义字段架构定义的自定义字段(请参阅“自定义字段”)。最大 64 KB。

响应

已创建。

internalId
string<uuid>

Localpayment 的实体标识符。请在其他所有 Entities endpoint 中使用它。

示例:

"5aced5da-40c1-4bec-85ff-c8cd1bcb4526"

externalId
string

您发送的标识符。

示例:

"550e8400-e29b-41d4-a716-446655440000"

type
enum<string>

INDIVIDUAL 或 COMPANY。

可用选项:
INDIVIDUAL,
COMPANY
示例:

"INDIVIDUAL"

status
enum<string>

实体状态。请参阅实体状态和错误代码。

可用选项:
PENDING_KYC,
IN_REVIEW,
ACTIVE,
REJECTED,
BLOCKED,
CLOSED
示例:

"PENDING_KYC"

name
string
示例:

"Jane"

lastname
string
示例:

"Doe"

birthdate
string<date>
示例:

"1990-01-15"

gender
string | null
nationality
string
示例:

"BRA"

birthCountry
string
示例:

"BRA"

residenceCountry
string
示例:

"BRA"

occupation
string | null
isPep
boolean
示例:

false

incorporationDate
string<date> | null
incorporationCountry
string | null
website
string | null
email
string
示例:

"jane.doe@example.com"

phone
object
address
object
attributes
object | null
documentationStatus
enum<string>

NO_FILES、PARTIAL 或 COMPLETE:表示已申报的文件中是没有、部分还是全部至少包含一个文件。它衡量的是文件是否存在,而非是否获批。

可用选项:
NO_FILES,
PARTIAL,
COMPLETE
示例:

"NO_FILES"

document
object

主要文档,包含其 documentId(上传文件时需要)、派生的状态以及当前的 proofs[]。

documents
object[]

其他已声明的文档(主要文档仅出现在 document 中),结构相同。

version
integer

实体版本。等于 ETag 标头;在 PATCH 请求中将其作为 If-Match 发送回。

示例:

0

createdAt
string<date-time>

ISO 8601 UTC 时间戳。

示例:

"2024-01-15T17:03:10Z"

updatedAt
string<date-time>

ISO 8601 UTC 时间戳。

示例:

"2024-01-15T17:03:10Z"

customFieldSchemaVersion
integer | null

用于验证属性的自定义字段架构版本,或 null。

最后修改于 2026年11月10日