# Payout Element Verification ::: tip This API verifies the format of the merchant-provided payee information fields (e.g., account number, name, ID, etc.) before initiating a payment. This ensures that the payee information complies with the required formatting when the transaction is initiated. This API is optional and recommended for merchants with withdrawal or payee information storage logic. Verification includes formatting (e.g., length, regularization, and more detailed algorithmic rules) and valid enumeration values. ::: ## 1. Initiate Verification [Payout Element Verification API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-paymentFieldValidation/post) structure is completely analogous to [Disbursement Request API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-paymentOrderPay/post). The top-level fields and field names within the Data body remain consistent with [Disbursement Request API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=en#/paths/aggregate-pay-api-gateway-paymentOrderPay/post). All fields follow the standard order interface structure. **Please pay special attention to the payee information field and submit it according to the corresponding requirements**. Untransmitted fields will not be validated. Transmitted fields that are in the order field list but do not fall within the corresponding payment method's rules will be marked as non-validated fields (`ignoredFields`). If they are not in the order field list, they will not be processed. ::: warning Note: In order to locate the payment method corresponding to the field that needs to be verified, please be sure to submit the fields related to `the following payment method`. ::: | Field Name | Type | Is this field required? | Format Description | Sample Value | | ------------------- | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | | country | string | Required | Country code, ISO 3166 Alpha-2 format (uppercase) | ID | | destinationCurrency | string | Required | Destination Currency, ISO 4217 Format (uppercase) | IDR | | paymentMethodType | enum | Required | Payment method type, enumeration values: `BANK_TRANSFER`, `WALLET`, `REALTIME_PAYMENT`, `CARRIER_BILLING`, `CARD`, `CASH` | BANK_TRANSFER | | clearingRail | enum | Conditional | Clearing network, enumeration values: `SWIFT`, `SEPA`, `LOCAL` | LOCAL | | chargeOption | enum | Conditional | Charge payment method. `SWIFT` payments must be sent via | OUR | | targetOrg | enum | Conditional | Target payment institution, such as `PIX`, `DANA`, `GCash`, etc., depending on the payment method requirements. | BCA | | payeeInfo.payeeType | enum | Optional | Payee type, enumeration values: `PERSONAL`, `CORPORATION` | PERSONAL | ### 1.1 Check Field Description - Account Information | Field Name | Type | Sample Value | | ----------- | ------ | ------------ | | accountNo | string | 0812345678 | | accountType | enum | P | | checkDigit | string | 12 | - Certificate Information | Field Name | Type | Sample Value | | ------------------ | ------ | ------------ | | documentType | enum | CPF | | documentId | string | 53106284097 | | documentIssueDate | string | 2020-01-01 | | documentExpireDate | string | 2030-01-01 | - Name information | Field Name | Type | Sample Value | | ---------- | ------ | ---------------- | | fullName | string | James Shri Kanta | | firstName | string | James | | middleName | string | Shri Williams | | lastName | string | Kanta | - Contact and Address Information | Field Name | Type | Sample Value | | ---------- | ------ | -------------- | | 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 | - Transaction Information | Field Name | Type | Sample Value | | ---------- | ------ | -------------------------- | | remark | string | Commission payment to Jack | | purpose | enum | PAYCMSN | ### 1.2 Field Format Description - Validation requirements for each field (such as format, length, regular expression, and dependencies) are dynamically loaded by the system based on the country, payment method, and clearing channel. Fields are divided into three categories: - Required fields (`required`): Validation will fail if not provided or if the format is incorrect. - Optional fields (`optional`): Validation is performed if provided; not providing a valid field will not affect validation. - Ignored fields (`ignored`): Fields are not considered in the current payment method field rules and are not validated when passed in. They are directly returned as `nonValidatedFields`. - Please note fields with dependencies: - If the payment method requires `documentType`, the `documentId` must be correctly passed when validating `documentType`. - If the payment method requires `accountType`, the `accountNo` must be correctly passed when validating `accountType`. ## 2. Request Example ### 2.1 Request Input Example ``` 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 Request Response Structure | Field | Type | Is this field required? | Description | | ------------------------- | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | code | string | Yes | Return code. `APPLY_SUCCESS` indicates a successful interface request; others indicate failures, such as `CONTROL ACT_INVALID`, `PARAMS_INVALID`, etc. | | msg | string | Yes | Return description | | data | object | No | Response data | | └ validationCode | string | No | Validation result code: `PASS` indicates all fields passed, `PARAMS_INVALID` indicates a field failed. | | └ validationFailedFields | map | No | Validation failed fields and error message (field name → error description) | | └ validationPassedFields | array | No | Field name that passed validation (structure: {"field": "xxx"}) | | └ ignoredFields | array | No | Field names not included in validation (structure: {"field": "xxx"}) | ### 2.3 Response Examples #### 2.3.1 Parameter Verification Successful ``` json { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "validationCode": "PASS", "validationPassedFields": [ { "field": "payeeInfo.name.firstName" } ] } } ``` #### 2.3.2 Parameter Verification Failed ``` 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 The Contract Has Not Been Signed ``` json { "msg": "Merchant has not signed the contract or payment methods.", "code": "CONTRACT_INVALID" } ``` #### 2.3.4 Required Parameter Error ``` json { "msg": "The [field] is incorrect.", "code": "PARAMS_INVALID" } ```