Payer Info Notification

When the system first obtains payer information, it pushes an additional independent notification to the merchant's payment_cl_name_notify_url, carrying the payer's name, bank account number, and bank code.

This notification is independent from the Deposit Transaction Result Notification:

• Deposit transaction result notification → Triggered when the order enters a successful state; pushed to notify_url
• Payer info notification → Triggered when payer information is first obtained; pushed to payment_cl_name_notify_url

A single order may receive both notifications (independent push, independent signature, independent response).

Use Cases

This notification is designed for reconciliation and risk control scenarios:

• Merchants need to obtain the payer's identity (name, bank account, bank) before or right after the order succeeds, for their own reconciliation system
• Risk control systems need to compare payer information against member-bound accounts

How to Enable

When creating a deposit order, include the optional payment_cl_name_notify_url parameter:

{
  "platform_id": "PF0002",
  "service_id": "SVC0015",
  "payment_cl_id": "DEVPM00014581",
  "amount": "50000000",
  "notify_url": "https://merchant.example.com/webhook/deposit",
  "payment_cl_name_notify_url": "https://merchant.example.com/webhook/payer-info",
  "request_time": "1595504136",
  "sign_type": "HMAC-SHA256",
  "sign": "..."
}

If not provided, this notification is disabled.

Request Information

• Request URL: The payment_cl_name_notify_url provided by the merchant when creating the deposit order
• Request Method: POST
• Content-Type: application/json;charset=utf-8

Request Parameters

Parameter	Required	Type	Description
payment_id	Yes	String	System order number
payment_cl_id	Yes	String	Merchant order number
payment_cl_name	Yes	String	Payer name
payment_cl_number	No	String	Payer bank account number
payment_cl_bank_name	No	String	Payer bank code (refer to the Vietnam Bank List)
sign_type	No	String	Signature algorithm identifier (included only for HMAC-SHA256 orders; see "Signature Algorithm" below)
sign	Yes	String	Order signature

Field Rules

• payment_cl_name: Raw payer name value; no formatting applied.
• payment_cl_number: Complete payer bank account number. If unavailable, this parameter is omitted from the body.
• payment_cl_bank_name: Payer bank code. Values follow the bank_name codes in the Vietnam Bank List (e.g., VCB, MB, TCB). If the bank cannot be determined, this parameter is omitted from the body.

Signature Algorithm

MD5 will be fully deprecated

MD5 signing will be fully deprecated in the future. Merchants integrating with this API are advised to switch to HMAC-SHA256.

The signature method is consistent with the Deposit Transaction Result Notification, determined per order by the sign_type specified at order creation

• Order created with sign_type omitted / set to "MD5" → This notification uses MD5 signing; the body does NOT contain the sign_type field
• Order created with sign_type = "HMAC-SHA256" → This notification uses HMAC-SHA256 signing; the body carries the sign_type: "HMAC-SHA256" field

Merchants should dispatch signature verification by whether the sign_type field is present:

• sign_type field absent → Verify with MD5
• sign_type = "HMAC-SHA256" → Verify with HMAC-SHA256

MD5 signature rules (MD5 orders):

1. Take all non-empty fields from the body, excluding sign and sign_type
2. Sort parameter names by ASCII code in ascending order
3. Join as key=value pairs separated by & (no URL encoding)
4. Append &{platform_service_sign_key} at the end
5. Apply MD5 hash to the complete string
6. Convert to a 32-character lowercase hexadecimal string

HMAC-SHA256 signature rules (HMAC-SHA256 orders):

Aligned with the Signature Specification — the body additionally contains sign_type: "HMAC-SHA256", and the signature is produced with HMAC-SHA256(param_str, platform_service_sign_key) as a 64-character lowercase hexadecimal string.

Request Examples

MD5 order (body does NOT contain sign_type)

{
  "payment_id": "PM00000102",
  "payment_cl_id": "97a968b4a9db497c8c03198e395a38c6",
  "payment_cl_name": "TRAN TRUNG HIEU",
  "payment_cl_number": "10066777777",
  "payment_cl_bank_name": "MB",
  "sign": "d2e4534fce8c1d1053bbf59fd8ae4464"
}

Name only (bank information unavailable):

{
  "payment_id": "PM00000103",
  "payment_cl_id": "a1c2d3e4f5g6h7i8",
  "payment_cl_name": "NGUYEN VAN A",
  "sign": "8a7b6c5d4e3f2g1h"
}

HMAC-SHA256 order (body carries sign_type)

{
  "payment_id": "PM00000102",
  "payment_cl_id": "97a968b4a9db497c8c03198e395a38c6",
  "payment_cl_name": "TRAN TRUNG HIEU",
  "payment_cl_number": "10066777777",
  "payment_cl_bank_name": "MB",
  "sign_type": "HMAC-SHA256",
  "sign": "e8a5c3f2d1b4a6e9c7f0d2b5a8e1c4f7d0b3a6e9c2f5d8b1a4e7c0f3d6b9a2e5"
}

Merchant Response

{ "error_code": "0000" }

Parameter	Type	Description
error_code	String	Returning "0000" indicates the merchant has processed the notification

Notes

• This endpoint is implemented by the merchant; our system calls it when the payer information is first obtained.
• Fully independent from notify_url: The trigger timing, push body, and signature of the two notifications are entirely separate. Merchants must implement handlers for each endpoint separately.
• This notification is sent only once (no retry). Merchants must ensure the endpoint is reliable. If the endpoint responds with a non-2xx status, the information will not be resent.
• All non-empty fields (except sign_type and sign) must participate in signing. Please iterate over all parameters in the request body to dynamically build the signature string; do NOT hardcode field names.
• Use non-empty fields to compute the signature, and read returned fields dynamically — additional fields may be added in the future (e.g., payment time, bank branch).