付款要素校验
本接口用于在实际发起出款前，对商户提供的收款人信息字段（如账户、姓名、证件等）进行格式规范的校验，确保发起交易时，收款人信息符合格式规则。该接口非必须接入，推荐具备提现或收款人信息保存逻辑的商户使用。校验范围包括填写格式是否正确（如长度、正则、更细化的算法规则）、是否为合法枚举值等。
1. 发起校验
付款要素校验 API 结构可完全参考申请付款 API，顶层字段、Data体中的字段名称均和申请付款 API 保持一致。所有字段遵循下单接口标准结构，请重点关注收款人信息字段并按照对应的要求进行上送。
未传字段将不参与校验；传入字段若在下单字段列表内但不属于对应支付方式的规则范围，将标记为非校验字段（ignoredFields）；若在下单字段列表外，则不会处理。
注意：
为了定位需要校验的字段对应的支付方式，请务必上送以下支付方式相关的字段。
| 字段名 | 类型 | 是否必填 | 格式说明 | 示例值 |
|---|---|---|---|---|
| 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 | DNI |
| documentId | string | 02376720575 |
| 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 |
| 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": "02376720575"
},
"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"
}