Payout Element Verification

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 structure is completely analogous to Disbursement Request API. The top-level fields and field names within the Data body remain consistent with Disbursement Request API. 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.

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 ional	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	DNI
documentId	string	02376720575
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

{
  "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 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

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

2.3.2 Parameter Verification Failed

{
    "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

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

2.3.4 Required Parameter Error

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