出款要素校验

Endpoint: POST /aggregate-pay/api/gateway/paymentFieldValidation
Tags: 付款

Description

本接口用于在实际发起出款前，对商户提供的收款人要素字段（如账户、姓名、证件等）进行结构化校验，确保发起交易时，收款人信息符合格式规则。校验范围包括填写格式是否正确（如长度、正则、更细化的算法规则）、是否为合法枚举值等。

该接口能力旨在帮助商户提前发现错误字段并前端报错给用户，提升出款成功率和用户体验。建议商户在收款人信息收集页面调用，用于检查参数格式。本接口仅用于静态字段格式校验，通过校验代表能够较大程度避免信息错误导致的交易失败，但并不能完全杜绝。不建议商户缓存字段配置，具体字段要求将随支付规则变更动态更新。

Parameters

Field	In	Type	Required	Constraints	Description
`Content-Type`	header	string	Yes
`sign`	header	string	Yes		签名信息请参考技术文档

Parameter Examples

Content-Type: "application/json"
sign: "FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A=="

Request Body

Content-Type: application/json

Field	Type	Required	Constraints	Description
`version`	string	Yes	maxLength: 8	接口版本当前值为：1.5
`keyVersion`	string	Yes	maxLength: 8	密钥版本当前值为：1
`requestTime`	string	Yes	maxLength: 32	请求时间，符合rfc3339规范，格式：yyyy-MM-dd'T'HH:mm:ss.SSSXXX 时间需要在当前时间两分钟内
`appId`	string	Yes	maxLength: 64	商户应用Id，PayerMax分配给商户应用的唯一标识
`merchantNo`	string	No	maxLength: 32	商户号，商户与PayerMax业务签约时生成的唯一标识
`data`	object	Yes		请求数据体
`data.country`	string	Yes	maxLength: 2	国家代码，大写字母，参见【支持的国家与币种】
`data.chargeOption`	string	No		费用承担模式，是否必传参照《付款申请模板及填写规范》
`data.clearingRail`	string	No		枚举值为：SWIFT, SEPA, LOCAL，分别对应签约的SWIFT、SEPA、Local Banks支付方式，请根据实际要用的支付方式来上送，请参照《付款申请模板及填写规范》
`data.sourceAccount`	string	No	maxLength: 3	扣款账户的币种代码，大写字母
`data.destinationCurrency`	string	No	maxLength: 3	到账币种，请参考【支付方式列表】，如有标明到账币种的，需要指定到账币种；若未标明，则到账币种仅支持本币，不需要进行指定
`data.payeeInfo`	object	Yes		收款方信息
`data.payeeInfo.paymentMethodType`	string	Yes	maxLength: 64	支付方式，参见【支付方式类型及目标机构说明】
`data.payeeInfo.targetOrg`	string	No	maxLength: 64	目标机构，参见【支付方式类型及目标机构说明】
`data.payeeInfo.payeeType`	string	No		收款方类型（PERSONAL/CORPORATION），默认PERSONAL
`data.payeeInfo.accountInfo`	object	No		收款账户信息
`data.payeeInfo.accountInfo.accountNo`	string	No	maxLength: 128	收款方账号，根据付款方式不同填入相应账号
`data.payeeInfo.accountInfo.accountType`	string	No		收款账户类型,在不同国家-支付方式下规范不同
`data.payeeInfo.accountInfo.checkDigit`	string	No		收款方账户验证数字
`data.payeeInfo.bankInfo`	object	No		收款方银行信息
`data.payeeInfo.bankInfo.bankCode`	string	No	maxLength: 64	用于识别特定金融机构下的收款方银行代码，在不同国家下填写规范不同，参见【付款申请模板及填写规范】以及【支持银行范围列表】
`data.payeeInfo.bankInfo.bankName`	string	No	maxLength: 255	收款方银行名称
`data.payeeInfo.bankInfo.bankBranch`	string	No	maxLength: 64	收款人银行网点号/分行号
`data.payeeInfo.bankInfo.bankCity`	string	No	maxLength: 255	收款方银行所在城市
`data.payeeInfo.bankInfo.corAccountNo`	string	No	maxLength: 128	收款方银行的代理账号（correspondent account）
`data.payeeInfo.name`	object	No		收款方姓名，支持英文、空格、逗号、中划线、点，在不同国家-支付方式下填写规范不同
`data.payeeInfo.name.firstName`	string	No	maxLength: 64	收款方名
`data.payeeInfo.name.middleName`	string	No	maxLength: 64	收款方中间名，多段中间名时，使用空格进行分隔
`data.payeeInfo.name.lastName`	string	No	maxLength: 64	收款方姓
`data.payeeInfo.name.fullName`	string	No	maxLength: 512	收款方全名
`data.payeeInfo.document`	object	No		收款方个人身份信息
`data.payeeInfo.document.documentType`	string	No	maxLength: 16	收款方个人身份证明类型，在不同国家下可选类型不同，参见《付款申请模板及填写规范》
`data.payeeInfo.document.documentId`	string	No	maxLength: 64	收款方个人识别号码，在不同国家下可选类型不同，参见《付款申请模板及填写规范》
`data.payeeInfo.document.documentIssueDate`	string	No	maxLength: 10	收款方个人识别号码生效日期，在不同国家下可选类型不同，yyyy-MM-dd格式
`data.payeeInfo.document.documentExpireDate`	string	No	maxLength: 10	收款方个人识别号码失效日期，在不同国家下可选类型不同，yyyy-MM-dd格式
`data.payeeInfo.address`	object	No		收款方地址信息
`data.payeeInfo.address.address`	string	No	maxLength: 512	收款方地址
`data.payeeInfo.address.city`	string	No	maxLength: 255	收款方城市
`data.payeeInfo.address.state`	string	No	maxLength: 255	州
`data.payeeInfo.address.zipCode`	string	No	maxLength: 32	收款方邮编
`data.payeeInfo.payeePhone`	string	No	maxLength: 64	收款方移动电话号码，在不同国家-支付方式下填写规范不同
`data.payeeInfo.birthDate`	string	No	maxLength: 10	收款方出生日期，yyyy-MM-dd格式
`data.payeeInfo.email`	string	No	maxLength: 64	收款方邮箱
`data.payeeInfo.payeeNationality`	string	No	maxLength: 2	收款人国籍，ISO 3166-1 alpha-2标准，如CN，US
`data.payeeInfo.payeeGender`	string	No	maxLength: 1	收款人性别，枚举值F 或M（F=Female，M=Male）
`data.payeeInfo.payeeBirthCountry`	string	No	maxLength: 2	收款人出生国家，ISO 3166-1 alpha-2标准，如CN，US
`data.payerInfo`	object	No		付款方信息
`data.payerInfo.name`	object	No		付款方姓名，支持英文、空格、逗号、中划线、点，在不同国家-支付方式下填写规范不同
`data.payerInfo.name.firstName`	string	No		付款方名
`data.payerInfo.name.middleName`	string	No		付款方中间名，多段中间名时，使用空格进行分隔
`data.payerInfo.name.lastName`	string	No		付款方姓
`data.payerInfo.name.fullName`	string	No		付款方全名
`data.expiryDays`	string	No		取款码有效天数，当前仅在FawryCash中有效，支持传入1~15整数（1=24Hours），其他值或不传则默认为7
`data.remark`	string	No		出款附言或备注，允许英文，数字，中划线，空格，点；受渠道约束，该字段可能会进行特殊处理，如超长截断或填充默认值
`data.notifyEmail`	string	No	maxLength: 64	收款方通知邮箱，目前只有个别支付方式会发送取款码邮件，比如FAWRY
`data.notifyPhone`	string	No	maxLength: 64	收款方通知电话
`data.purpose`	string	No	maxLength: 32	出款目的，枚举值，ISUBIL:向公用事业提供商付款(i.e.水电煤账单)； EPTOUR:旅游业； EPTKAG:支付旅游门票或旅行社费用； ISPAYR:支付工资； ISPAYRA:支付代理工资； ISGDDS:货物买卖； ISSCVE:购买和销售服务； ISSUPP:供应商付款； ISLOGS:物流和运输服务付款； INCEN:激励/促销/用户获取活动； GAME:游戏设备、游戏币和其他游戏物品； SAMENM:企业同名账户转账； PAYCMSN:报销/福利发放/佣金发放； SAMENMC:法人/股东/董事个人账户； AGOPEXP:代运营费用结算； ADEXP:广告费用结算；RFND:退货；SMCNTST:子商户结算；LGTEP:供应商付款-物流费用结算；GOODPAY:供应商付款-货款结算；SINVEST:股票投资；FINVEST:基金投资；TAXPAY:纳税/支付税款；LOANPAY:支付贷款； OTHER:其他；

Example

json

{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2025-07-02T08:43:43.362+00:00",
  "appId": "appId",
  "merchantNo": "merchantNo",
  "data": {
    "sourceAccount": "USD",
    "destinationCurrency": "IDR",
    "country": "ID",
    "payeeInfo": {
      "paymentMethodType": "BANK_TRANSFER",
      "targetOrg": "BCA",
      "payeeType": "",
      "accountInfo": {
        "accountNo": "SA1210987654987654987654",
        "accountType": "",
        "checkDigit": ""
      },
      "bankInfo": {
        "bankCode": "NCBKSAJE",
        "bankName": "Raiffeisenbank",
        "bankBranch": "",
        "bankCity": "asdasd",
        "corAccountNo": "30101810200000000700"
      },
      "name": {
        "firstName": "Williams",
        "middleName": "middleName",
        "lastName": "lastName",
        "fullName": "Chiamaka chukwudolue"
      },
      "document": {
        "documentType": "",
        "documentId": "",
        "documentIssueDate": "1994-06-21",
        "documentExpireDate": ""
      },
      "address": {
        "address": "test address",
        "city": "",
        "zipCode": ""
      },
      "payeePhone": "79123456789",
      "birthDate": "1994-06-21",
      "email": "example@gmail.com",
      "payeeNationality": "ID",
      "payeeGender": "F",
      "payeeBirthCountry": "ID"
    },
    "payerInfo": {
      "name": {
        "fullName": ""
      },
      "subMerchantNo": "",
      "businessLegalName": "name yssss",
      "registrationCountry": "Eg",
      "merchantCategoryCode": "",
      "payerId": "23434234"
    },
    "expiryDays": "",
    "remark": "remark test"
  }
}

Responses

200

Field	Type	Required	Description
`code`	string	Yes	返回码，APPLY_SUCCESS代表成功。只代表接口请求成功，不代表订单状态。
`msg`	string	Yes	返回描述，’Success.’
`data`	object	Yes	返回数据体
`data.validationCode`	string	Yes	校验结果码，PASS：没有校验失败的字段，PARAMS_INVALID：存在校验失败的字段
`data.validationPassedFields`	array[object]	Yes	通过校验的字段集合
`data.validationPassedFields[].field`	string	No	通过校验的字段路径
`data.ignoredFields`	array[object]	Yes	忽略校验的字段集合
`data.ignoredFields[].field`	string	Yes	忽略校验的字段路径
`data.validationFailedFields`	array[object]	Yes	校验失败的字段集合
`data.validationFailedFields[].field`	string	Yes	校验失败的字段路径
`data.validationFailedFields[].errorMsg`	string	Yes	校验失败原因

Response Example

json

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "validationCode": "PARAMS_INVALID",
    "validationPassedFields": [
      {
        "field": "payeeInfo.name.fullName"
      }
    ],
    "ignoredFields": [
      {
        "field": "payeeInfo.bankInfo.bankCode"
      },
      {
        "field": "payeeInfo.birthDate"
      },
      {
        "field": "payeeInfo.bankInfo.bankCity"
      },
      {
        "field": "payeeInfo.document.documentIssueDate"
      },
      {
        "field": "payeeInfo.name.lastName"
      },
      {
        "field": "remark"
      },
      {
        "field": "payeeInfo.payeePhone"
      },
      {
        "field": "payeeInfo.bankInfo.corAccountNo"
      },
      {
        "field": "payeeInfo.email"
      },
      {
        "field": "payeeInfo.address.address"
      },
      {
        "field": "payeeInfo.bankInfo.bankName"
      },
      {
        "field": "payeeInfo.name.middleName"
      },
      {
        "field": "notifyEmail"
      }
    ],
    "validationFailedFields": [
      {
        "field": "payeeInfo.name.firstName",
        "errorMsg": "The payeeInfo.name.firstName should not exceed 64 characters"
      },
      {
        "field": "payeeInfo.accountInfo.accountNo",
        "errorMsg": "Please enter numbers."
      }
    ]
  }
}

出款要素校验 ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example ​

Responses ​

200 ​

Response Example ​