> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义字段

> 将与 Localpayment 约定的额外 KYC/KYB 数据存储在属性中，并根据您商家的自定义字段架构进行验证。

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

## 先决条件

* 与您的客户经理商定并由 Localpayment 发布的自定义字段方案。
* Stage 访问令牌。请参阅 [获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)。

## 工作原理

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["您的客户经理<br/>商定字段：键、类型、约束"]:::lp --> B["Localpayment<br/>发布 schema 版本 N"]:::lp
    B --> C["您的后端<br/>GET /api/entity/v1/custom-fields/schema"]
    C --> D["Entities API<br/>200：JSON Schema；若未发布则返回 404"]:::lp
    D --> E["您的后端<br/>POST /api/entity/v1/entities 附带 attributes"]
    E --> F["Entities API<br/>201：customFieldSchemaVersion N"]:::lp
    E --> G["Entities API<br/>400 CUSTOM_FIELDS_INVALID<br/>当某个值违反 schema 时"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

* **未发布架构：** `attributes` 将按发送内容原样接受，[获取自定义字段架构](https://docs.localpayment.com/zh/reference/get-custom-fields-schema.md) 返回 404 `CUSTOM_FIELD_SCHEMA_NOT_FOUND`。
* **已发布架构：** 验证十分严格。未知键、缺失的必填键、错误的类型、长度、模式和范围都会被拒绝，并返回 400 `CUSTOM_FIELDS_INVALID`。每个实体都会记录其验证时所使用的 `customFieldSchemaVersion`。
* **每个商户一个架构**，同时适用于 `INDIVIDUAL` 和 `COMPANY`。仅对公司有意义的字段定义为可选。

## 字段类型

| 类型 | 可用约束 |
| - | - |
| `STRING` | minLength, maxLength, pattern (RE2 syntax) |
| `NUMBER` | min, max |
| `DATE` | min, max (YYYY-MM-DD) |
| `ENUM` | options（必填，唯一值） |
| `BOOLEAN` | 没有任何 |
| OBJECT, LIST | 嵌套子项或项目。LIST 表支持 minItems 和 maxItems 参数。 |

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

## 阅读架构

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl https://api.stage.localpayment.com/api/entity/v1/custom-fields/schema \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN"
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reasonForAccountOpening": {
      "type": "string",
      "title": "Reason for account opening",
      "enum": [
        "receive_payments_for_goods_and_services",
        "payroll",
        "other"
      ]
    },
    "sourceOfFundsAndIncome": {
      "type": "string"
    },
    "numberOfEmployees": {
      "type": "string",
      "enum": [
        "1-10",
        "11-50",
        "51-200",
        "200+"
      ]
    },
    "estimatedAnnualRevenueUsd": {
      "type": "string"
    },
    "estimatedMonthlyVolumeUsd": {
      "type": "string"
    },
    "businessActivityDescription": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "countryTaxResidence": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "socialMedia": {
      "type": "string"
    },
    "emailPixKey": {
      "type": "string"
    },
    "percentageOfOwnership": {
      "type": "string"
    },
    "hasControl": {
      "type": "string"
    },
    "documentCountry": {
      "type": "string"
    },
    "countryOfTaxId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

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

## 发送这些值

这些值通过 [创建实体](https://docs.localpayment.com/zh/reference/create-entity.md) 和 [更新实体](https://docs.localpayment.com/zh/reference/update-entity.md) 中的 `attributes` 传递：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "attributes": {
    "reasonForAccountOpening": "receive_payments_for_goods_and_services",
    "sourceOfFundsAndIncome": "sales_of_goods_and_services",
    "numberOfEmployees": "11-50",
    "estimatedAnnualRevenueUsd": "1m_to_10m",
    "estimatedMonthlyVolumeUsd": "50000",
    "businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
    "countryTaxResidence": "BRA",
    "socialMedia": "https://www.linkedin.com/company/example",
    "emailPixKey": "test@example.com"
  }
}
```

超出架构范围的值将返回 400 `CUSTOM_FIELDS_INVALID`，`details` 中每个有问题的字段对应一个条目：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}
```

在调用 API 之前，请先在您这一侧根据架构验证 `attributes`，并将每个 `details` 条目映射回您的表单，以便用户修正该值。

## 更改架构

Localpayment 会将架构变更作为新版本发布。现有实体保留其 `customFieldSchemaVersion`，新的写入则根据最新发布的版本进行验证。请联系您的客户经理来添加、放宽或移除字段。

> [!WARNING]
>
> 模式发布后，任何未在其中定义的键都将被拒绝。在通过集成发送新字段之前，请先协调好模式变更。

## 下一步

> [card] [获取自定义字段架构](https://docs.localpayment.com/zh/reference/get-custom-fields-schema.md)
>
> 响应格式和错误代码。

> [card] [通过实体共享 KYB 信息](https://docs.localpayment.com/zh/docs/share-kyb-information-through-entities.md)
>
> 用于虚拟账户受益人的自定义字段。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.