Guides

Account Validation API

Service Code: 16

Account Validation API is used to validate a beneficiary bank account or e-wallet account before a transfer is made. This API confirms whether the beneficiary account can be used for disbursement based on the details provided in the request.

When used as part of the Disbursement flow, Account Validation is a mandatory step and must be performed for every transfer request. A disbursement should only be submitted after the account validation process is completed successfully.

A response code 2001600 means that the request has been successfully received and accepted for asynchronous processing. It does not mean that the beneficiary account has already been confirmed as valid. The final verification result must always be determined from the callback response.

Clients must rely on the latestVerificationStatus field in the callback to determine the final verification result:

  • 00 - INITIATED: the verification process has started
  • 01 - VALID: the beneficiary account is valid and may proceed to disbursement
  • 02 - INVALID: the beneficiary account is invalid and must not be used for disbursement
  • 03 - ERROR: an error occurred during the verification process and the validation may be performed again

If a 5XX16XX response code is received, the request should not be treated as a final failed verification, as the callback is typically received within a few seconds. If no callback is received within 15 seconds, the same request may be sent again using the same request identifier to check whether the original request is already being processed. If no callback is received within 1 minute, the Account Validation request may be retried.

The additionalInfo.customerReference returned in the callback must be stored and included in the Disbursement request, as this value is used as the validated beneficiary reference for the transfer.

Important Notes:

  • A successful initial API response does not confirm that the beneficiary account is valid. Always use the callback result as the source of truth.
  • Only beneficiary accounts with latestVerificationStatus = 01 (VALID) should proceed to disbursement.
  • If latestVerificationStatus = 02 (INVALID), the disbursement must not be attempted.
  • If latestVerificationStatus = 03 (ERROR), the validation may be performed again.
  • Each Account Validation request must use a new and unique X-EXTERNAL-ID. Reusing the same value will be treated as a duplicate request and rejected.

E-Wallet KYC / Non-KYC Information Handling

For e-wallet beneficiaries, the callback does not return a dedicated KYC flag. However, the format of beneficiaryAccountName can generally be used as a supporting indicator for merchant-side handling.

In general:

  • KYC / verified accounts usually return a formal beneficiary name, commonly in uppercase
  • Non-KYC accounts may return a display name, username, mixed-case name, alphanumeric value, or even a phone number

General handling per e-wallet:

  • DANA
    KYC accounts usually return a masked formal name in uppercase, not a phone number
  • ShopeePay
    KYC accounts usually return a formal name in uppercase; lowercase, mixed-case, username, or alphanumeric values may indicate non-KYC / display name
  • OVO and GoPay
    KYC accounts usually return a formal name in uppercase; if the returned account name is a phone number, it may indicate a non-KYC account

As a general merchant-side rule, if beneficiaryAccountName is returned in uppercase formal name format, it may be treated as a KYC / verified account.