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 after the upgrade; 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

This notification currently uses MD5, and will be upgraded to HMAC-SHA256 on 2026/05/01

Merchants must implement signature verification that dispatches by the sign_type field in advance:

• sign_type field absent → Verify with MD5 (current behavior)
• sign_type = "HMAC-SHA256" → Verify with HMAC-SHA256 (behavior after the upgrade)

After the upgrade, pure MD5 verification will no longer apply. Please complete the compatibility work before 2026/05/01.

Current signature rules (MD5):

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

Signature rules after upgrade (HMAC-SHA256, from 2026/05/01):

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

Current Version (MD5, 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"
}

Upgraded Version (HMAC-SHA256, from 2026/05/01, body includes 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.
• 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).