跳转到主要内容
自定义字段允许您的商户账户存储标准实体模型未包含的 KYC/KYB 数据,例如业务活动、资金来源、预估交易量或本地标识符。Localpayment 为您的商户定义一个架构,您在创建或更新实体时,将这些值通过 attributes 发送。

先决条件

  • 与您的客户经理商定并由 Localpayment 发布的自定义字段方案。
  • Stage 访问令牌。请参阅 获取访问令牌。

工作原理

  • 未发布架构: attributes 将按发送内容原样接受,获取自定义字段架构 返回 404 CUSTOM_FIELD_SCHEMA_NOT_FOUND。
  • 已发布架构: 验证十分严格。未知键、缺失的必填键、错误的类型、长度、模式和范围都会被拒绝,并返回 400 CUSTOM_FIELDS_INVALID。每个实体都会记录其验证时所使用的 customFieldSchemaVersion。
  • 每个商户一个架构,同时适用于 INDIVIDUAL 和 COMPANY。仅对公司有意义的字段定义为可选。

字段类型

键采用 camelCase 格式,并以小写字母开头(^[a-z][a-zA-Z0-9_]{0,63}$)。attributes 最大可达 64 KB(413 PAYLOAD_TOO_LARGE)。

阅读架构

Request
Response
默认响应为 JSON Schema (2020-12)。添加 ?format=definition 可改为获取原生字段列表。

发送这些值

这些值通过 创建实体 和 更新实体 中的 attributes 传递:
超出架构范围的值将返回 400 CUSTOM_FIELDS_INVALID,details 中每个有问题的字段对应一个条目:
在调用 API 之前,请先在您这一侧根据架构验证 attributes,并将每个 details 条目映射回您的表单,以便用户修正该值。

更改架构

Localpayment 会将架构变更作为新版本发布。现有实体保留其 customFieldSchemaVersion,新的写入则根据最新发布的版本进行验证。请联系您的客户经理来添加、放宽或移除字段。
模式发布后,任何未在其中定义的键都将被拒绝。在通过集成发送新字段之前,请先协调好模式变更。

下一步

获取自定义字段架构

响应格式和错误代码。

通过实体共享 KYB 信息

用于虚拟账户受益人的自定义字段。
最后修改于 2026年11月10日