Disbursement Field Validation

Endpoint: POST /aggregate-pay/api/gateway/paymentFieldValidation
Tags: Disbursement Service

Description

This interface is used to perform structured validation on the payee information fields (such as account number, name, ID, etc.) provided by the merchant before initiating an actual payout. It ensures that the payee information complies with format rules when the transaction is initiated. The validation scope includes checking whether the format is correct (e.g., length, regular expressions, more detailed algorithmic rules) and whether the values are valid enumerations.

The purpose of this interface is to help merchants identify erroneous fields in advance and display frontend error messages to users, thereby improving payout success rates and user experience. Merchants are advised to call this interface on the payee information collection page to check parameter formats. This interface is solely for static field format validation. Passing the validation indicates a high likelihood of avoiding transaction failures due to incorrect information, but it does not completely eliminate the possibility. Merchants are discouraged from caching field configurations, as specific field requirements will be dynamically updated in accordance with changes in payment rules.

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		API version. Current value: 1.5
`keyVersion`	string	Yes		Signature Algorithm Version, Current value: 1
`requestTime`	string	Yes		Request time, compliant with rfc3339 specification, format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX The time must be within two minutes of the current time
`appId`	string	Yes		Merchant AppId，The unique identifier assigned to the merchant app by PayerMax
`merchantNo`	string	No	maxLength: 32	Merchant Id, the unique identifier generated when the merchant signs the contract with PayerMax
`data`	object	Yes		Request data body.
`data.country`	string	Yes	maxLength: 2	Country code, using capital letters, please refer:【Supported countries and currencies】.
`data.chargeOption`	string	No		Whether charge bearer mode of fees is required, please refer: 【Disbursement Application Template and Filling Specifications】
`data.clearingRail`	string	No		Enumerated values: SWIFT, SEPA, LOCAL, corresponding to the contracted payment methods SWIFT, SEPA, and Local Banks, respectively. Please provide the value based on the actual payment method being used, please refer: 【Disbursement Application Template and Filling Specifications】
`data.sourceAccount`	string	No	maxLength: 3	Currency code of the deduction account, in uppercase letters.
`data.destinationCurrency`	string	No	maxLength: 3	The currency that the beneficiary receives. Please refer to the 【Payment Method Types List】. If the receiving currency is indicated in the payment method, please specify it. If not indicated, the receiving currency is limited to the local currency and no specification is required.
`data.payeeInfo`	object	Yes		Payee Information.
`data.payeeInfo.paymentMethodType`	string	Yes	maxLength: 64	Payment method types, please refer:【Payment Method Types and Target Org】.
`data.payeeInfo.targetOrg`	string	No	maxLength: 64	Target organization, please refer:【Payment Method Types and Target Org】.
`data.payeeInfo.payeeType`	string	No		Payee type (PERSONAL/CORPORATION), default to PERSONAL
`data.payeeInfo.accountInfo`	object	No		Payee account information
`data.payeeInfo.accountInfo.accountNo`	string	No	maxLength: 128	Payee account, fill in the corresponding account number according to the payment method.
`data.payeeInfo.accountInfo.accountType`	string	No		The type of receiving account is regulated differently in different countries and payment methods.
`data.payeeInfo.accountInfo.checkDigit`	string	No		Verification number of payee’s account.
`data.payeeInfo.bankInfo`	object	No		Receiving bank information
`data.payeeInfo.bankInfo.bankCode`	string	No	maxLength: 64	It is used to identify the bank code of the payee under a specific financial institution, and the filling specifications are different in different countries, refer to 【Disbursement Application Template and Filling Instructions】以及【List of supported bank ranges】.
`data.payeeInfo.bankInfo.bankName`	string	No	maxLength: 255	Name of payee’s bank.
`data.payeeInfo.bankInfo.bankBranch`	string	No	maxLength: 64	Payee’s bank branch number/branch number.
`data.payeeInfo.bankInfo.bankCity`	string	No	maxLength: 255	City where the recipient’s bank is located.
`data.payeeInfo.bankInfo.corAccountNo`	string	No	maxLength: 128	Agent account number of the payee’s bank(correspondent account).
`data.payeeInfo.name`	object	No		The name of the payee, which supports English, spaces, commas, dashes, and dots, and can be filled in according to different standards in different countries and payment methods.
`data.payeeInfo.name.firstName`	string	No	maxLength: 64	First name of payee.
`data.payeeInfo.name.middleName`	string	No	maxLength: 64	The payee’s Middle name is separated by spaces when there are multiple Middle name.
`data.payeeInfo.name.lastName`	string	No	maxLength: 64	Family name of payee.
`data.payeeInfo.name.fullName`	string	No	maxLength: 512	Full name of payee.
`data.payeeInfo.document`	object	No		Receiving document information.
`data.payeeInfo.document.documentType`	string	No	maxLength: 16	The type of the payee’s personal identity certificate, the optional types are different in different countries, please refer: 【Disbursement Application Template and Filling Specifications】
`data.payeeInfo.document.documentId`	string	No	maxLength: 64	Payee’s personal identification number. The Option type varies in different countries, please refer: 【Disbursement Application Template and Filling Specifications】
`data.payeeInfo.document.documentIssueDate`	string	No	maxLength: 10	The effective date of the payee’s personal identification number, the optional type is different in different countries, the format is "yyyy-MM-dd".
`data.payeeInfo.document.documentExpireDate`	string	No	maxLength: 10	The expiration date of the payee’s personal identification number, the optional type is different in different countries, the format is "yyyy-MM-dd".
`data.payeeInfo.address`	object	No		Receiving address information.
`data.payeeInfo.address.address`	string	No	maxLength: 512	Address of payee.
`data.payeeInfo.address.city`	string	No	maxLength: 255	City of payee.
`data.payeeInfo.address.state`	string	No	maxLength: 255	State.
`data.payeeInfo.address.zipCode`	string	No	maxLength: 32	Postal code of payee.
`data.payeeInfo.payeePhone`	string	No	maxLength: 64	The recipient’s mobile phone number is filled in according to different standards in different countries and payment methods.
`data.payeeInfo.birthDate`	string	No	maxLength: 10	Payee’s date of birth, in the format of "yyyy-MM-dd".
`data.payeeInfo.email`	string	No	maxLength: 64	Mailbox of payee.
`data.payeeInfo.payeeNationality`	string	No	maxLength: 2	payee Nationality, CN, US etc country code
`data.payeeInfo.payeeGender`	string	No	maxLength: 1	payee Gender, F or M, (F=Female，M=Male)
`data.payeeInfo.payeeBirthCountry`	string	No	maxLength: 2	payee BirthCountry, CN, US etc country code
`data.payerInfo`	object	No		Payer Information.
`data.payerInfo.name`	object	No		The name of the payer, which supports English, spaces, commas, dashes, and dots, and can be filled in according to different standards in different countries and payment methods.
`data.payerInfo.name.firstName`	string	No		First name of payer.
`data.payerInfo.name.middleName`	string	No		The payer’s Middle name is separated by spaces when there are multiple Middle name.
`data.payerInfo.name.lastName`	string	No		Family name of payer.
`data.payerInfo.name.fullName`	string	No		Full name of payer.
`data.expiryDays`	string	No		The validity days of the withdrawal code are currently only valid in FawryCash. It supports inputing integers in range of 1 to 15 (1=24Hours), and defaults to 7 if other values are not input.
`data.remark`	string	No		Postscript or remarks for disbursement, allows format of English, numbers, dash lines, spaces and dots; Due to channel constraints, this field may undergo special processing, such as ultra long truncation or filling in default values.
`data.notifyEmail`	string	No	maxLength: 64	Recipient notification email. Currently, only certain payment methods, such as FAWRY, send withdrawal code emails.
`data.notifyPhone`	string	No	maxLength: 64	Recipient notification phone number.
`data.purpose`	string	No	maxLength: 32	Disbursement purpose,enumeration value, ISUBIL:Pay to utilities (i.e. water, electricity, gas bills); EPTOUR:Tourism; EPTKAG:Pay for travel tickets or travel agency fees; ISPAYR:Pay Salary; ISPAYRA:Pay Agent Salary; ISGDDS:Goods Trade; ISSCVE:Purchase and Sale of Services; ISSUPP:Supplier Payment; ISLOGS:Logistics and Transportation Service Payment; INCEN:Incentive/Promotion/User Acquisition Activity; GAME:Gaming Equipment, Game Coins, and Other Game Items; SAMENM:Same Name Business Account Transfer; PAYCMSN:Reimbursement/Benefit Distribution/Commission Distribution; SAMENMC:Legal Person/Shareholder/Director Personal Account; AGOPEXP:Agency operating expenses; ADEXP:Advertising expenses;RFND:Refund;SMCNTST:Sub merchant settlement;LGTEP:Logistics expenses;GOODPAY:Goods payment;SINVEST:Investment in shares;FINVEST:Fund investment;TAXPAY:Tax payment;LOANPAY:Payment of loans; OTHER: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	API response code, ‘APPLY_SUCCESS’ means success. Indicates that the interface request is successful, but does not indicate the order status.
`msg`	string	Yes	Response description, ‘Success.’
`data`	object	Yes	Response data body.
`data.validationCode`	string	Yes	Verification result code, PASS: no field failed verification, PARAMS_INVALID: there is a field that failed verification
`data.validationPassedFields`	array[object]	Yes	The list of fields that passed the validation.
`data.validationPassedFields[].field`	string	No	The path of the field that passed the validation
`data.ignoredFields`	array[object]	Yes	A collection of fields that ignore validation
`data.ignoredFields[].field`	string	Yes	Ignore validation field paths
`data.validationFailedFields`	array[object]	Yes	The list of fields that failed validation
`data.validationFailedFields[].field`	string	Yes	The path of the field that failed the validation
`data.validationFailedFields[].errorMsg`	string	Yes	Verification failure reason

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."
      }
    ]
  }
}

Disbursement Field Validation ​

Description ​

Parameters ​

Parameter Examples ​

Request Body ​

Example ​

Responses ​

200 ​

Response Example ​