Refund Process Flow
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the refund process within the zalopay library. The system allows for programmatically refunding a previously completed transaction and subsequently querying the status of that refund request. The entire process is orchestrated through API calls to the ZaloPay platform, secured with HMAC signatures.
The refund flow consists of two primary actions: initiating a refund for a specific transaction and checking the status of that refund. Both actions require a valid configuration, including an App ID and the appropriate cryptographic keys, and rely on unique identifiers from the original payment.
Initial Configuration
Before any refund operations can be performed, the application must be configured with credentials provided by ZaloPay. These settings are fundamental for authenticating requests to the ZaloPay API.
| Parameter | Type | Description |
|---|---|---|
app_id | String | The application's unique identifier. |
key1 | String | The first key used for generating the HMAC signature for API requests. |
key2 | String | The second key used for validating the callback data from ZaloPay (not used in refund flow). |
endpoint | String | The base URL for the ZaloPay API endpoints. |
Sources: config/config.js, lib/zalopay.js:7-11
Refund Initiation
To start a refund, a request must be sent to the ZaloPay refund endpoint. This requires the transaction ID of the original payment (zp_trans_id) and a new, unique ID for the refund request (m_refund_id).
Sources: example/refund.js, lib/zalopay.js:63-82
Refund Request Parameters
The ZaloPay.refund() method constructs and sends the refund request. The following parameters are required:
| Parameter | Type | Description | Example Source |
|---|---|---|---|
app_id | String | The application's unique identifier from the configuration. | config.app_id |
m_refund_id | String | A unique identifier for the merchant's refund request. Must be unique for each refund attempt. | yyMMdd_app_id_trans_id |
timestamp | Number | The timestamp in milliseconds when the refund request is created. | Date.now() |
zp_trans_id | String | The transaction ID provided by ZaloPay for the original successful payment. | 190416000000051 |
amount | Number | The amount to be refunded. | 50000 |
description | String | A description for the refund transaction. | ZaloPay Intergration test |
mac | String | The HMAC-SHA256 signature generated from the request data. See Signature Generation. | - |
Sources: example/refund.js:9-15, lib/zalopay.js:68-75
Refund Initiation Sequence
The following diagram illustrates the sequence of events when initiating a refund.
This diagram shows the client application calling the library's refund method, which then prepares the data, signs it, and sends it to the ZaloPay API.
Sources: lib/zalopay.js:63-82, example/refund.js:18-23
Querying Refund Status
After a refund is initiated, its status can be checked using the m_refund_id that was sent in the initiation request.
Sources: example/getrefundstatus.js, lib/zalopay.js:84-100
Refund Status Query Parameters
The ZaloPay.getRefundStatus() method requires the following parameters to check the status of a refund:
| Parameter | Type | Description |
|---|---|---|
app_id | String | The application's unique identifier from the configuration. |
m_refund_id | String | The unique identifier for the merchant's refund request. |
timestamp | Number | The timestamp in milliseconds when the query request is created. |
mac | String | The HMAC-SHA256 signature generated from the request data. See Signature Generation. |
Sources: example/getrefundstatus.js:9-12, lib/zalopay.js:89-92
Refund Status Query Sequence
The diagram below shows the process of querying the status of a previously initiated refund.
This diagram shows the client application calling the getRefundStatus method, which signs the request and sends it to the ZaloPay API to retrieve the current status.
Sources: lib/zalopay.js:84-100, example/getrefundstatus.js:14-19
Core Logic and Components
Signature Generation
All requests to the ZaloPay refund and query endpoints must be authenticated with a Message Authentication Code (MAC). The library uses HMAC with the SHA-256 algorithm for this purpose.
The signature is generated from a |-delimited string of specific request parameters. The exact composition of this string differs between the refund initiation and the status query.
Refund Initiation Signature
The data string is formed as: app_id|zp_trans_id|amount|description|timestamp
// Source: lib/zalopay.js:74-75
const data = this.config.app_id + "|" + params.zp_trans_id + "|" + params.amount + "|" + params.description + "|" + params.timestamp;
body.mac = hmac.sha256(data, this.config.key1);
Refund Status Query Signature
The data string is formed as: app_id|m_refund_id|timestamp
// Source: lib/zalopay.js:91-92
const data = this.config.app_id + "|" + params.m_refund_id + "|" + params.timestamp;
body.mac = hmac.sha256(data, this.config.key1);
The hmac.sha256 function is a utility that performs the standard HMAC-SHA256 hashing.
Sources: lib/zalopay.js:74-75, 91-92, lib/utils.js:10-12
Overall Refund Flow
The following flowchart provides a high-level overview of the complete refund lifecycle, from initiation to status verification.
This diagram shows that a successful original payment is a prerequisite. The flow then proceeds to refund initiation, and if successful, the system can later query the refund status using the m_refund_id.
Sources: example/refund.js, example/getrefundstatus.js, lib/zalopay.js
Summary
The refund process is a critical post-payment feature handled by the zalopay library. It involves two distinct, secure API calls: one to initiate the refund and another to query its status. Both operations are protected by HMAC-SHA256 signatures, ensuring the integrity and authenticity of the requests. The process is dependent on identifiers from the original transaction (zp_trans_id) and a unique merchant-generated ID for the refund itself (m_refund_id).