# 付款要素校验

::: tip  
本接口用于在实际发起出款前，对商户提供的收款人信息字段（如账户、姓名、证件等）进行格式规范的校验，确保发起交易时，收款人信息符合格式规则。该接口非必须接入，推荐具备提现或收款人信息保存逻辑的商户使用。校验范围包括填写格式是否正确（如长度、正则、更细化的算法规则）、是否为合法枚举值等。
:::

## 1. 发起校验

[付款要素校验 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentFieldValidation/post) 结构可完全参考[申请付款 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderPay/post)，顶层字段、Data体中的字段名称均和[申请付款 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderPay/post) 保持一致。所有字段遵循下单接口标准结构，**请重点关注收款人信息字段并按照对应的要求进行上送**。

未传字段将不参与校验；传入字段若在下单字段列表内但不属于对应支付方式的规则范围，将标记为非校验字段（`ignoredFields`）；若在下单字段列表外，则不会处理。

::: warning 注意：
为了定位需要校验的字段对应的支付方式，请务必上送`以下支付方式`相关的字段。
:::

| 字段名              | 类型   | 是否必填    | 格式说明                                                                                               | 示例值        |
| ------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------ | ------------- |
| country             | string | Required    | 国家代码，ISO 3166 Alpha-2 格式（大写）                                                                | ID            |
| destinationCurrency | string | Required    | 到账币种，ISO 4217 格式（大写）                                                                        | IDR           |
| paymentMethodType   | enum   | Required    | 支付方式类型，枚举值：`BANK_TRANSFER`, `WALLET`, `REALTIME_PAYMENT`, `CARRIER_BILLING`, `CARD`, `CASH` | BANK_TRANSFER |
| clearingRail        | enum   | Conditional | 清算网络，枚举值：`SWIFT`, `SEPA`, `LOCAL`                                                             | LOCAL         |
| chargeOption        | enum   | Conditional | 费用承担方式，`SWIFT`付款需要传                                                                        | OUR           |
| targetOrg           | enum   | Conditional | 目标支付机构，例如`PIX`、`DANA`、`GCash`等，视支付方式要求上送                                         | BCA           |
| payeeInfo.payeeType | enum   | Optional    | 收款方类型，枚举值：`PERSONAL`, `CORPORATION`                                                          | PERSONAL      |

### 1.1 校验字段说明

- 账户信息

| 字段名      | 类型   | 示例值     |
| ----------- | ------ | ---------- |
| accountNo   | string | 0812345678 |
| accountType | enum   | P          |
| checkDigit  | string | 12         |

- 证件信息

| 字段名             | 类型   | 示例值      |
| ------------------ | ------ | ----------- |
| documentType       | enum   | CPF         |
| documentId         | string | 53106284097 |
| documentIssueDate  | string | 2020-01-01  |
| documentExpireDate | string | 2030-01-01  |

- 姓名信息

| 字段名     | 类型   | 示例值           |
| ---------- | ------ | ---------------- |
| fullName   | string | James Shri Kanta |
| firstName  | string | James            |
| middleName | string | Shri Williams    |
| lastName   | string | Kanta            |

- 联系方式与地址信息

| 字段名     | 类型   | 示例值         |
| ---------- | ------ | -------------- |
| payeePhone | string | 6281234567890  |
| email      | string | test@gmail.com |
| address    | string | Jl. Thamrin 10 |
| city       | string | Jakarta        |
| state      | string | Jakarta        |
| zipCode    | string | 12345          |
| birthDate  | string | 1990-01-01     |

- 交易信息

| 字段名  | 类型   | 示例值                     |
| ------- | ------ | -------------------------- |
| remark  | string | Commission payment to Jack |
| purpose | enum   | PAYCMSN                    |

### 1.2 字段格式说明

- 每个字段的校验要求（如格式、长度、正则、依赖关系）由系统根据国家、支付方式、清算通道动态加载。字段分为三类：

  - 必填字段（`required`）：若未提供或格式错误，将导致校验失败；

  - 选填字段（`optional`）：提供则校验；不提供不影响校验通过；

  - 忽略字段（`ignored`）：不纳入当前支付方式字段规则，传入亦不校验，直接作为`nonValidatedFields`返回。

- 请注意存在依赖关系的字段：

  - 在支付方式要求必填`documentType`时，校验`documentId`时必须正确上送`documentType`；

  - 在支付方式要求必填`accountType`时，校验`accountNo`时必须正确上送`accountType`。

## 2. 请求示例

### 2.1 请求参数示例

``` json
{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2025-05-09T15:00:00.000+08:00",
  "appId": "ee8856246fc346798a0238720824c3b8",
  "merchantNo": "P04010130683638",
  "data": {
    "country": "ID",
    "chargeOption": "",
    "clearingRail": "",
    "destinationCurrency": "IDR",
    "payeeInfo": {
      "paymentMethodType": "WALLET",
      "targetOrg": "DANA",
      "accountInfo": {
        "accountNo": "xieliuyuan@ushareit.com",
        "accountType": "E",
        "checkDigit": "12"
      },
      "document": {
        "documentType": "CPF",
        "documentId": "53106284097"
      },
      "name": {
        "firstName": "firstName",
        "middleName": "middleName",
        "lastName": "lastName",
        "fullName": "SASD"
      },
      "address": {
        "address": "test address 111"
      },
      "payeePhone": "09233333333"
    },
    "payerInfo": {
      "name": {
        "fullName": "testSimpleName"
      }
    },
    "remark": "",
    "notifyEmail": ""
  }
}
``` 

### 2.2 请求响应结构

| 字段                      | 类型   | 是否必填 | 说明                                                                                          |
| ------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| code                      | string | 是       | 返回码，`APPLY_SUCCESS`表示接口请求成功；其余为失败，如`CONTRACT_INVALID`、`PARAMS_INVALID`等 |
| msg                       | string | 是       | 返回说明                                                                                      |
| data                      | object | 否       | 响应数据体                                                                                    |
| └ validationCode         | string | 否       | 校验结果码：`PASS`表示全部通过，`PARAMS_INVALID`表示存在失败字段                              |
| └ validationFailedFields | map    | 否       | 校验失败字段及错误信息（字段名 → 错误描述）                                                  |
| └ validationPassedFields | array  | 否       | 校验通过的字段名（结构：{"field": "xxx"}）                                                    |
| └ ignoredFields          | array  | 否       | 不参与校验的字段名（结构：{"field": "xxx"}）                                                  |

### 2.3 请求响应示例

#### 2.3.1 参数校验成功

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "validationCode": "PASS",
        "validationPassedFields": [
            {         
              "field": "payeeInfo.name.firstName"
            }           
    ]
  }
}
``` 

#### 2.3.2 参数校验失败

``` json
{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "validationPassedFields": [
            {
                "field": "notifyEmail"
            }
        ],
        "ignoredFields": [
            {
                "field": "payeeInfo.name.fullName"
            },
            {
                "field": "payeeInfo.name.lastName"
            },
            {
                "field": "remark"
            },
            {
                "field": "payeeInfo.name.middleName"
            }
        ],
        "validationCode": "PARAMS_INVALID",
        "validationFailedFields": [
            {
                "field": "payeeInfo.name.firstName",
                "errorMsg": "The payeeInfo.name.firstName should not exceed 64 characters"
            },
            {
                "field": "payeeInfo.accountInfo.accountNo",
                "errorMsg": "Please enter 11 digits starting with 0."
            }
        ]
    }
}
```

#### 2.3.3 合约未签约或找不到对应支付方式

``` json
{
  "msg": "Merchant has not signed the contract or payment methods.",
  "code": "CONTRACT_INVALID"
}
```

#### 2.3.4 必填参数错误

``` json
{
  "msg": "The [field] is incorrect.",
  "code": "PARAMS_INVALID"
}
```