ZaloPay APIs QuickPay Integration Document

 A. Overview
o Introduction
o Environment information
 B. APIs description
o 1. Create Order
o 2. Callback
o 3. Query Order Status
o 4. Refund Order Status
o 5.Query Refund Order Status
 C. Error Code Information
o 1. Return_code
o 2. Sub_return_code

Page 1 / 29
A. Overview

Introduction

 This document provides APIs for merchants to integrate payment solution to their applications.

Environment information

Environment Link

Sanndbox https://sb-openapi.zalopay.vn

Prod https://openapi.zalopay.vn

Interface Name Entry Point Direction

Create Order /v2/quick_pay Merchant to ZaloPay

Get Order’s Status /v2/query Merchant to ZaloPay

Refund Order /v2/refund Merchant to ZaloPay

Refund Order’s Status /v2/query_refund Merchant to ZaloPay

Payment Notification Provided by the Merchant ZaloPay to Merchant

Page 2 / 29
B. APIs description

1.Create Order

 Sequence Diagrams

Page 3 / 29
 Entry Point

Name Description
Protocol HTTPS
URI /v2/quick_pay
Method POST
application/x-www-form-urlencoded
Content-Type
application/json

 Request Parameters

Data
No Parameter Max Length Required Description Example data
Type
The app identifier is provided
1 app_id Int ✔ 1727
by ZaloPay.
Identification information of
the application user: Id /
Username / Name / Phone Num
2 app_user String 50 ✔ / Email. If you cannot identify user123
the user, you can use the default
information, such as the
application name

Page 4 / 29
 Data
No Parameter Max Length Required Description Example data
Type
Order's transaction code. Must
be preceded by yymmdd of the
current date. The transaction-
code's format should
be yymmddOrder identifier
3 app_trans_id String 40 ✔ 2001148007242
yymmdd is correct TimeZone
Vietnam (GMT+7) (Because of
cross check transactions is in
Vietnam time and date)
The time of order creation,
which calculated in
4 app_time Long ✔ milliseconds, and couldn't over 1459823610957
15 minutes from the time of
payment
5 amount Long ✔ The amount of the order (VND) 50000
6 title String 256 Optional title of order.
<Name Merchant/Service>
- Payment order
The description of the order,
#<trans_id>
7 description String 256 ✔ used to display to users on the
Ex:
ZaloPay app
ZLP - Payment order
#180208_007242

Page 5 / 29
 Data
No Parameter Max Length Required Description Example data
Type
ZaloPay will notify to this URL
only when the payment is
8 callback_url String success; If not provided, the
default app Callback URL will
be used.
JSON string describes the
9 device_info String 256
device specification.
Identification of the service /
service group that partner was
10 sub_app_id String 50 sub123
registered with ZaloPay (only
applicable to special partners)
[{"itemid":"knb","itename
Additional data, defined by
":"kim nguyen
11 item String 2048 ✔ Merchant. Use "[]" when
bao","itemprice":198400,"i
empty.
temquantity":1}]
Merchant's item data. {"promotioninfo":"","merc
12 embed_data String 1024 ✔
Use "{}" when empty. hantinfo":""}
Authentication information of c8f49d523336f0a182586a
the order, see how to create 70b71c20da96
13 mac String ✔
authentication information for 4d37954711de9273152b5
orders 00df74c0d
The currency of order. Default
14 currency String VND
is VND.

Page 6 / 29
 Data
No Parameter Max Length Required Description Example data
Type
Scanned from ZaloPay by
Merchant's terminal and
encrypted by Public Key
15 payment_code String ✔
provided by
ZaloPay =RSA(paymentCode
Raw, publicKey)
16 userIP String User IP address

Specific embed_data's fields

Data
No Parameter Format Description Example
Type
Redirect to this url after successful /
failure payment via ZaloPay Gateway
{"redirecturl":
1 Redirecturl String URL (This will override the
"https://docs.zalopay.vn/result"}
merchant's redirect url registered with
ZaloPay)

Page 7 / 29
 Data
No Parameter Format Description Example
Type
Add information into the
section Management of transaction
details on Merchant site, If the column
{"columninfo": "{\"branch_id\":
{"column_na does not yet exist, please go to
JSON \"HCM\",\"store_id\":
2 Columninfo me": the Display data configuration setting
String \"CH123\",\"store_name\":
"value"} to configure
\"Saigon Centre\"}"}
Note: For offline payment, it is necessary
to transmit information such as
branch_id, store_id, store_name, ...
{"promotioninfo":
JSON {"campaignc
3 Promotioninfo Use to launch promotions campaign "{\"campaigncode\":\"blackfrida
String ode":"code"}
y\"}"}
-Payment information
-Only needed when you need to receive
money for different accounts.
4 zlppaymentid String -ZaloPay system will generate a Payment {"zlppaymentid": "P4201372"}
code (corresponding to each partner bank
account provided) and send it back to the
partner to set up.

Page 8 / 29
 Create authentication information

mac = HMAC(hmac_algorihtm, mackey, hmacinput)

 With:

 hmac_algorithm: is a security method registered by Merchant with ZaloPay, the default is HmacSHA256
 mackey: provided by ZaloPay at registration
 hmacinput: app_id +”|”+ app_trans_id +”|”+ app_user +”|”+ amount +"|"+ app_time +”|”+ embed_data +"|"+
item+"|"+ paymentCodeRaw

 Response Parameters

No Parameter Data Type Description

1: Success
1 return_code Int
2: Failure
2 return_message String Description of status code
3 sub_return_code Int Status code detail
4 sub_return_message String Detail description of status code
5 is_processing Boolean Process’s status
6 zp_trans_id String ZaloPay's transaction code

Page 9 / 29
Example:

Request Response
{ {
"amount": "69000", "return_code": 3,
"app_id": "124705", "return_message": "[Pending] Giao dịch vẫn đang được xử lý",
"app_time": "1652694044613", "sub_return_code": 10,
"app_trans_id": "220516_16404400234", "sub_return_message": "[Pending] Giao dịch vẫn đang được xử
"app_user": "ZaloPay", lý",
"description": "ZaloPay Demo", "is_processing": true,
"embed_data": "{}", "zp_trans_id": 220516000060744
"item": "[]", }
"payment_code": "541080213600000311",
"mac":
"e0f7394178511e911782b9aa9d54bd722637ad32bd601287f6c6e
cf542aaab1d"
}

Page 10 / 29
2.Callback

 Sequence Diagrams

Page 11 / 29
 API specification

If ZaloPay successfully get money from user, then ZaloPay Server will notify to MerchantServer via CallbackURL which had
been registered with ZaloPay or from callback_url. MerchantServer use callbackkey (provided by ZaloPay) to validate
callback's data.

 Entry Point

Name Description
Protocol HTTPS
URI provided by the merchant
Method POST
Content-Type application/json
 Request Parameters

No Parameter Data Type Description

1 Data JSON String ZaloPay transaction data callback to the application
Confirmation of order information, using callbackkey (had been provided) to verify the
2 Mac String
order
Callback type

3 Type String 1: Order

2: Agreement

Page 12 / 29
Callback_order_data

No Parameter Data Type Description Example Data

1 The app identifier is
app_id Int 1727
provided by ZaloPay.
2 app_trans_id String Order's app_trans_id 180208181007242
3 app_time Long Order's app_time 1460543835849
4 app_user String Order's app_user user123
5 Amount received
amount Long 50000
(VND)
6 {"promotioninfo":"","merchantinfo":""}
Order's embed_data
embed_data JSON String
• Required json string
Data empty: {}
7 [{"itemid":"knb","itename":"kim nguyen
Order's item
JSON Array bao","itemprice":198400,"itemquantity":1}]
item • Required json array
String
string
Data empty: []
8 ZaloPay's
zp_trans_id Long 160413000003083
Transaction code
9 ZaloPay's
Transaction trading
server_time Long 1460543836370
time (unix timestamp
in milliseconds)'

Page 13 / 29
 No Parameter Data Type Description Example Data
10 channel Int Payment channel 38
11 The identifier of
7ZMSl3nEg5sOUJzOLSoUFT8xKNQVaLOLXH
zp_user_id String ZaloPay user per
B--8Eytqc
Merchant app_id
12 user_fee_amount Long Fee (VND) 220
13 discount_amount Long Discount (VND) 10000

 Check if callback is valid

reqmac = HMAC(hmac_algorithm, callbackkey, callback_data.data)

if (reqmac == callback_data.mac) {
// valid callback
} else {
// invalid callback
}

 With:

 hmac_algorithm: is a security method registered by Merchant with ZaloPay, the default is HmacSHA256
 callbackkey: provided by ZaloPay at registration
 callback_data: is data requested by ZaloPay to Merchant's callback API when ZaloPay has successfully collected
money from customers.

Page 14 / 29
 Supported payment channels:

No Value Channel
1 36 Visa/Master/JCB
2 37 Bank Account
3 38 ZaloPay Wallet
4 39 ATM
5 41 Visa/Master Debit

 Response Parameters: The data that AppServer returns to ZaloPayServer after got the callback

No Parameter Data Type Description

1 1: Success
2: ZaloPay zptransid or apptransid
return_code Int
is duplicated
<>: failure (not callback again)
2 return_message String Details of the status code

Note

After 15 minutes from the time of the order establishment, if merchant still do not receive callback from ZaloPay, merchant
need to call API Get order status proactively to get the final result.

Page 15 / 29
3.Query Order Status

When the payment is successful, ZaloPay will call the callback (notify) to the Merchant, then the Merchant updates the status of
Successful orders on the Merchant's system. But in reality, the callback may be missed due to Network timeout, Merchant Service
unavailable Internal error,... so Merchant needs to make the call of the API to query the order status.

App Server send request to ZaloPay Server to get the transaction's payment status.

Note

1. A single order is valid only within 15 minutes after create.

2. When it is less than 15 minutes from the time of the order creation. In the following cases, It is necessary to repeat the API calling
process to get the final result

 When return_code = 3 - User hasn't paid the order or transaction is processing

Page 16 / 29
 Sequence Diagrams

 Entry Point

Name Description
Protocol HTTPS
URI /v2/query
Method POST
application/x-www-form-urlencoded
Content-Type
application/json

Page 17 / 29
 Request Parameters

No Parameter Data Type Required Description

1 app_id Int ✔ The app identifier is provided by ZaloPay.
2 app_trans_id String ✔ Order's app_trans_id
Authenticate data information
3 mac String ✔ mac = HMAC(hmac_algorithm, mackey,
app_id+"|"+app_trans_id+"|"+mackey)

 Response Parameters

No Parameter Data Type Description

1 : SUCCESS
1 return_code Int 2 : FAIL
3 : PROCESSING
2 return_message String Order's status information
3 sub_return_code Int Detail transaction code
4 sub_return_message String Detail description of the order transaction
5 is_processing Boolean Process's status
6 amount Long Amount received (only make sense when the payment is successful)
7 zp_trans_id Long ZaloPay's transaction code
8 server_time Long ZaloPay's Transaction trading time (unix timestamp in milliseconds)

Page 18 / 29
Example

Request Response
{ {
"app_id": "124705", "return_code": 1,
"app_trans_id": "220420_11232000092", "return_message": "Giao dịch thành công",
"mac": "sub_return_code": 1,
"483cdbb1d4eae8a399a3d17a6793f6a93487b167be32c109ad "sub_return_message": "Giao dịch thành công",
c2c70691c65802" "is_processing": false,
} "amount": 69000,
"zp_trans_id": 220420000029880,
"server_time": 1650428630520
}

Page 19 / 29
4.Refund Order

 Refund Rules

PAYMENT METHOD WALLET REFUND TO REFUND TIME SUPPORTED BANKS

ZaloPay Walet ZaloPay Walet Immediately
ATM / Bank Vietcombank, Vietinbank, BIDV,
ZaloPay Walet Immediately
ZaloPay App Account Sacombank, Eximbank, SCB, Viet
Capital Bank, JCB
Visa / Master /
Card 5 - 7 working days
JCB
ATM / Bank 3 - 5 working days ABBank, ACB, Agribank, Bac A
Bank Account
Account (depend on the bank) Bank, Bao Viet Bank, BIDV, DongA
Bank, Eximbank, GP Bank, HD Bank,
Card payment / Bank Lien Viet Post Bank, Maritime Bank,
Account via ZaloPay MB Bank, NamA Bank, NCB, Viet
Gateway Visa / Master / 5 - 7 working days Capital Bank, OCB, Ocean Bank, PG
Card
JCB (depend on the bank) Bank, Sacombank, Saigon Bank, SCB,
SeA Bank, SHB, Techcombank, TP
Bank, VIB

 Note: For transactions that apply promotions of ZaloPay or partners. The refund amount must be a full refund. Depend on the
bank, the refund time will be vary.

Page 20 / 29
 Sequence Diagrams

Page 21 / 29
 Entry Point

Name Description
Protocol HTTPS
URI /v2/refund
Method POST
application/x-www-form-urlencoded
Content-Type
application/json

 Request Parameters

No Parameter Data Type Max Length Required Description

• Merchant must be generate merchant own transaction code
1 m_refund_id String 45 ✔ when submit refund requirement.
• Format: yymmdd_appid_xxxxxxxxxx
2 app_id Int ✔ The app identifier is provided by ZaloPay.
• Transaction code, which want to be refund.
3 zp_trans_id Long 15 ✔
• Transaction code of ZaloPay, retrieved from callback data
4 amount Long ✔ Refund amount for users
• Time to refund (unix timestamp in millisecond).
5 timestamp Long 13 ✔
• The time of making the refund, is calculated in milliseconds

Page 22 / 29
 No Parameter Data Type Max Length Required Description
Authenticate information (See how to create authenticate
6 mac String ✔
information)
7 description String 100 Refund reason

 Create authentication information

mac = HMAC(hmac_algorithm, mackey, hmacinput)

 With:

 hmac_algorithm: is a security method registered by Merchant with ZaloPay, the default is HmacSHA256
 mackey: provided by ZaloPay at registration
 hmacinput: app_id +"|"+ zp_trans_id +"|"+ amount +"|"+ description +"|"+ timestamp

 Response Parameters

No Parameter Data Type Description

1 : Successful refund
1 return_code Int 2 : Refund failure, need to redo
3 : Refunding processing, call getRefundStatus API to get final result
2 return_message String Status code information
3 sub_return_code Int Detailed status codes
4 sub_return_message String Order status details

Page 23 / 29
 No Parameter Data Type Description
5 refund_id Long ZaloPay refund's transaction code, need to save for cross-check then

Example

Request Response
{ {
"app_id": "124705", "return_code": 3,
"m_refund_id": "220420_124705_11360700093", "return_message": "Giao dịch đang refund!",
"zp_trans_id": "220420000029880", "sub_return_code": 2,
"amount": "69000", "sub_return_message": "Giao dịch đang refund!",
"timestamp": "1650429367066", "refund_id": 220420000028403
"mac": }
"1772f6fe1dd3ac6b1c52d12ff4cb3349707abe697d628c06319f8
2a3052fa524",
"description": "ZLP - Refund TransID 220420000029880"
}

Page 24 / 29
5.Query Refund Order Status

 Sequence Diagrams

 Entry Point

Name Description
Protocol HTTPS
URI /v2/query_refund
Method POST
application/x-www-form-urlencoded
Content-Type
application/json

Page 25 / 29
 Request Parameters

No Parameter Data Type Max Length Required Description

1 app_id string ✔ The app identifier is provided by ZaloPay.
• The transaction code, which was generated by merchant
2 m_refund_id string 45 ✔ when querying refund transaction.
• Format: yymmdd_appid_xxxxxxxxxx
3 timestamp long ✔ The time call API (timestamp in millisecond)
= HMAC(hmac_algorithm, mackey,
4 mac string ✔
app_id+"|"+m_refund_id+"|"+timestamp)

 Response Parameters

No Parameter Data Type Description

1 return_code int status code
2 return_message string status information
3 sub_return_code int status code detail
4 sub_return_message string detail description of status code

Page 26 / 29
Example

Request Response
{ {
"app_id": "124705", "return_code": 1,
"m_refund_id": "220420_124705_11360700093", "return_message": "Giao dịch thành công!",
"timestamp": "1650429570877", "sub_return_code": 1,
"mac": "sub_return_message": "Giao dịch thành công!"
"f689e80854fbc7d3473eb558a8f415628160e46e238af307d5f2c24cc3 }
151211"
}

Page 27 / 29
C. Error Code Information

1.Return_code

No Status code Short description Type

1 1 SUCCESS Successful
2 2 FAIL Error
3 3 PROCESSING Pending

2.Sub_return_code codes

No Error Code Short Description Meaning Type

1 1 SUCCESS Success Successful
Missing or misspelled app_id.
2 -2 APPID_INVALID Correct: app_id. Wrong appid: Merchant Error
appId, Appid,...
Params request is wrong or Mac
3 -53 HMAC_INVALID Merchant Error
key wrong
App_time param of request order
4 -54 TIME_INVALID not unix timestamp in milisecond Merchant Error
format
ZPW_BALANCE_NOT_ENO User balance not enough for
5 -63 User Error
UGH paymet

Page 28 / 29
 DUPLICATE_APPS_TRANS
6 -68 Transaction is duplicate Merchant Error
_ID
App_trans_id param of request
7 -92 APPTRANSID_INVALID order format wrong, need begin Merchant Error
yyMMdd (GMT+7)
8 -101 ORDER_NOT_EXISTS Order not exists Merchant Error
9 - 217 ZPBANK_CHARGE_FAIL Payment fail User and System Error
10 -401 ILLEGAL_DATA_REQUEST Invalid data Merchant Error
ILLEGAL_APP/
11 -402 Invalid app code/ signature Merchant Error
SIGNATURE_REQUEST
ILLEGAL_CLIENT_REQUE
12 -405 Invalid request Merchant Error
ST
13 -429 LIMIT_REQUEST_REACH Limit request Merchant Error
14 -500 SYSTEM_ERROR The system is error System Error

Page 29 / 29