Refund Endpoint
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Refund Endpoint provides the functionality to process refunds for transactions originally made through the ZaloPay gateway. This is an internal API endpoint that receives a refund request, constructs a request compliant with the ZaloPay API specification, sends it to the ZaloPay gateway, and processes the response.
The overall architecture follows a layered approach, separating the API handling, business logic, and gateway communication. The process involves receiving a client request, validating it, invoking the core payment service, which then uses a dedicated ZaloPay gateway implementation to handle the external API call. Security is handled by generating a Message Authentication Code (MAC) for each request sent to ZaloPay.
High-Level Refund Flow
The following diagram illustrates the sequence of operations when a refund request is initiated.
This diagram shows the flow from the initial client request through the internal service layers to the final interaction with the external ZaloPay API.
Sources: api/api.go:27, api/handler/payment.go:88-103, payment/service.go:42-45, payment/zalopay/gateway.go:102-132
API Endpoint
The refund functionality is exposed via a single POST endpoint.
- Endpoint:
POST /api/v1/payment/refund - Handler:
handler.Payment.Refund
This route is defined within the v1 API group and is handled by the Refund method on the payment handler.
Sources: api/api.go:20, api/api.go:27
Request Body
The API expects a JSON body with the following structure.
| Field | Type | Description |
|---|---|---|
zp_trans_id | string | The ZaloPay transaction ID to be refunded. |
amount | int64 | The amount to refund. |
description | string | A description for the refund transaction. |
Sources: api/handler/payment.go:83-87
Handler Logic (handler.Payment.Refund)
The Refund method in api/handler/payment.go is responsible for:
- Binding the incoming JSON request to a
refundRequeststruct. - Calling the
payment.Service.Refundmethod with the request parameters. - Handling any errors returned from the service layer.
- Returning the refund result from the service as a JSON response with an HTTP 200 status code on success.
Sources: api/handler/payment.go:88-103
Service Layer (payment.Service)
The service layer acts as an intermediary between the API handler and the ZaloPay gateway, containing the core business logic.
- Method:
Service.Refund(ctx context.Context, req *entity.RefundRequest) (*entity.RefundResponse, error)
This method simply delegates the call to the configured ZaloPay gateway's Refund method, passing along the necessary parameters. This design decouples the API from the specific payment gateway implementation.
Sources: payment/service.go:42-45
ZaloPay Gateway (zalopay.Gateway)
This component is responsible for all direct communication with the ZaloPay API for refunds.
Refund Process Flow
The Refund method within the gateway follows a precise sequence to ensure a valid request is sent to ZaloPay.
This flowchart details the steps taken inside the zalopay.Gateway.Refund method.
Sources: payment/zalopay/gateway.go:102-132
Data Structures
ZaloPay Refund Request
This struct represents the payload sent directly to the ZaloPay API.
| Field | Type | Description | JSON Tag |
|---|---|---|---|
AppID | int | The application ID from config. | app_id |
ZpTransID | string | The ZaloPay transaction ID to refund. | zp_trans_id |
Amount | int64 | The amount to be refunded. | amount |
Description | string | A description for the refund. | description |
Timestamp | int64 | The request timestamp in milliseconds. | timestamp |
Mac | string | The generated Message Authentication Code. | mac |
MRefundID | string | A unique merchant ID for the refund transaction. | m_refund_id |
Sources: payment/zalopay/refund.go:5-13
ZaloPay Refund Response
This struct represents the JSON response received from the ZaloPay API.
| Field | Type | Description | JSON Tag |
|---|---|---|---|
ReturnCode | int | The result code of the refund operation. | return_code |
ReturnMessage | string | A message describing the result. | return_message |
SubReturnCode | int | A more detailed sub-result code. | sub_return_code |
SubReturnMessage | string | A more detailed result message. | sub_return_message |
RefundID | string | The ZaloPay-generated ID for the refund. | refund_id |
Sources: payment/zalopay/refund.go:15-21
Security: MAC Generation
To authenticate requests, a MAC (Message Authentication Code) is generated using HMAC-SHA256.
The mac.New function is used for this purpose. It computes the hash based on a specific data string format and a secret key.
- Algorithm: HMAC-SHA256
- Secret Key: The
Key2from the application configuration is used. - Data String Format: The data to be hashed is a string constructed by joining the following fields with a
|separator:
app_id|zp_trans_id|amount|description|timestamp
// Example from payment/zalopay/gateway.go
data := fmt.Sprintf("%d|%s|%d|%s|%d", g.cfg.AppID, req.ZpTransID, req.Amount, req.Description, timestamp)
zaloPayReq.Mac = mac.New(data, g.cfg.Key2)
Sources: payment/zalopay/gateway.go:114-115, payment/zalopay/mac.go:7-11, config/config.go:10
Configuration
The refund functionality relies on several configuration values defined in config/config.go.
| Field | Type | Description | Environment Variable |
|---|---|---|---|
AppID | int | The application ID provided by ZaloPay. | APP_ID |
Key1 | string | The first secret key provided by ZaloPay. | KEY_1 |
Key2 | string | The second secret key, used for MAC generation. | KEY_2 |
Endpoint | string | The base URL for the ZaloPay gateway API. | ENDPOINT |
The refund endpoint URL is constructed by appending /v2/refund to the base Endpoint.
Sources: config/config.go:8-12, payment/zalopay/gateway.go:104, payment/zalopay/gateway.go:118
Summary
The Refund Endpoint is a well-structured feature that securely interacts with the ZaloPay payment gateway. It follows a clean, layered architecture that separates concerns between API routing, business logic, and external gateway communication. The use of HMAC-SHA256 for request signing ensures the integrity and authenticity of refund requests sent to ZaloPay. The entire process is driven by configuration, making it adaptable to different environments.