Authorize Payment

Overview

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

Communication Protocols

Merchant accessing the Zalopay service and calling the API must follow the following rules:

#	Describe
Transmission Method	In order to ensure transaction security, HTTPS transmission is adopted
Submission Method	Submit by POST method
Data Format	Submit and return data in application/json, application/x-www-form-urlencoded format
Character Encoding	UTF-8 character encoding
Authentication Algorithm	HmacSHA256
Authentication Requirements	Both request and received data need to verify the authentication information
Process Logic	First refer to the return of the protocol field, then refer to the code in the response message, and finally refer to the transaction status

Authentication Rules

#	Describe
Authentication Algorithm	HmacSHA256
Authentication Information	mac = HMAC(hmac_algorithm, key, hmacinput) with: - hmac_algorithm: is a security method registered by Merchant with Zalopay, the default is HmacSHA256 - key: provided by Zalopay at registration - hmacinput: specified by each API

APIs Description

1. API list

Environment	Link
Sandbox	https://sb-openapi.zalopay.vn
Prod	https://openapi.zalopay.vn

No.	Interface Name	Entry Point	Direction	Card Tokenization	Zalopay E-Wallet
1	Create Binding for Agreement	/v2/agreement/bind	merchant to Zalopay	x	x
2	Query Payment Token	/v2/agreement/query	merchant to Zalopay	x	x
3	Unbind an Agreement	/v2/agreement/unbind	merchant to Zalopay	x	x
4	Authorize	/preauth/authorize	merchant to Zalopay		x
5	Capture	/preauth/capture	merchant to Zalopay		x
6	Cancel	/preauth/cancel	merchant to Zalopay		x
7	Pay Direct	/preauth/pay	merchant to Zalopay	x	x
8	Get Status	/preauth/query	merchant to Zalopay	x	x
9	Get Payable	/preauth/get_payable	merchant to Zalopay		x
10	Refund	/preauth/m_refund	merchant to Zalopay	x	x
11	Get Refund Status	/preauth/query_refund	merchant to Zalopay	x	x
12	Create Order for Card Payment	/preauth/create	merchant to Zalopay	x

Notification:

Interface Name	Entry Point	Direction
Binding Notification	Provided by the merchant	Zalopay to merchant
Payment Notification	Provided by the merchant	Zalopay to merchant

2. API parameter transfer rules

Required	Description
M	Mandatory
O	Optional

3. API detail

3.1. Binding

3.1.1. Binding

Description

This API is used for creating a new binding for an agreement of a user in tokenization flow.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	app_id	Int	Required		The app identifier is provided by Zalopay.
2	binding_data	JSON String	Required	2048	This field contains detail binding information for billing purposes. Default value is "{}"
3	app_trans_id	String	Required	40	The transaction id is used to initialize a binding request, generated by merchant system, unique transaction ID of application
4	binding_type	String	Required	20	Specify which type of binding - WALLET: Zalopay Wallet - CARD: ATM
5	identifier	String	Required	128	User's identifier on the merchant system, it can be the merchant user's id, phone number, email...
6	max_amount	Int64	Required		Maximum permissible amount. The default is real balance. Default value is 0
7	redirect_url	String	Optional	256	URL of merchant binding page(web), be used in the desktop binding scenario. After the binding process finished, Zalopay auto-debit binding page will redirect to merchant binding page via redirect URL with the binding result
8	redirect_deep_link	String	Optional	256	deep-link of merchant app, be used in the mobile binding scenario. After the binding process finished, Zalopay app will open the merchant app via redirect deep link with the binding result
9	callback_url	String	Optional	256	After the binding process finished successfully, Zalopay auto-debit system will notify to merchant system via this URL
10	req_date	Int64	Required		Current unix timestamp in milliseconds
11	mac	String	Required	64	Security string for request validation. - mac = HMAC(HmacSHA256, macKey, macInput) - macInput = app_id|apps_trans_id|binding_data|binding_type|identifier|max_amount|req_date - macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Max length	Description	Note
1	return_code	Int		1: Success, 2: Failure
2	return_message	String	256	Description of return code
3	sub_return_code	Int		Detail error code
4	sub_return_message	String	256	Detail error message
5	binding_token	String	64	The token for confirming.
6	deep_link	String	256	The deep-link for confirming the agreement in the mobile app to app scenario.	Only use for wallet binding Merchant uses the deep link to launch the Zalopay app for confirm binding
7	binding_qr_link	String	245	The URL for the user confirming the agreement in the desktop or mobile web scenario.	Use in both wallet and card binding Merchant opens "binding_qr_link" on PC Browser or Mobile Browser Card binding: user input card information for confirm binding Wallet binding: - PC Browser: user uses Zalo/Zalopay App to scan QRCode for confirm binding - Mobile Browser: this web page will auto invoke Zalo/Zalopay app for confirm binding
8	short_link	String	245	The URL for the user agreement in the desktop web/app scenario. Merchant need gen QR from this link.	Only use for wallet binding: - Merchant need gen QR code from this link and display on Merchant site. - User uses Zalo/Zalopay App to scan QR code for confirm binding

Example

Request

{
  "app_id": "2688",
  "binding_data": "{}",
  "app_trans_id": "221011_09171700003",
  "binding_type": "WALLET",
  "identifier": "NHAN",
  "max_amount": 0,
  "redirect_url": "",
  "redirect_deep_link": "",
  "callback_url": "",
  "req_date": "1665454637789",
  "mac": "fde19dbf326322a614094ef27e38a43601112bda2cb950539f4830d5fa0b759b"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "sub_return_code": 1,
  "sub_return_message": "Success",
  "binding_token": "221011VvZq80GobDg8gTgXPeeLMaZMy",
  "deep_link": "zalopay://launch/app/732?view=authorize&b=221011VvZq80GobDg8gTgXPeeLMaZMy",
  "binding_qr_link": "https://dev-binding.zalopay.vn?binding_token=221011VvZq80GobDg8gTgXPeeLMaZMy",
  "short_link": "https://zlpdev-agp.zalopay.vn/oauthbe/agreement/221011VvZq80GobDg8gTgXPeeLMaZMy"
}

3.1.2. Query Binding

Description

After the binding has been created successfully, this API is used to get merchant callback data

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	app_id	Int64	required		The app id of the merchant.
2	app_trans_id	String	required	40	The merchant's unique id for the binding (TXID of binding transaction)
3	binding_type	String	required	20	Specify which type of binding - WALLET: Zalopay Wallet - CARD: ATM
4	req_date	Int64	required		Current unix timestamp in milliseconds
5	mac	String	required	64	Security string for request validation. macInput = app_id|app_trans_id|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Max length	Description
1	return_code	Int		1: Success, 2: Failure, 3: Waiting Note: To get more information, get from sub_return_code
2	return_message	String	256	Description of return_code
3	sub_return_code	Int		Detail error code
4	sub_return_message	String	256	Description of sub_return_code
5	data	JSON Object	4096	The merchant callback data Note: See Merchant Callback Data as bellow for detailed structure

Detail of Merchant Callback Data

No	Field name	Datatype	Max length	Description
1	app_id	Int		The app id of the merchant.
2	binding_data	String	2048	The binding data was sent in bind request.
3	app_trans_id	String	40	The merchant's unique id for the binding(TXID of binding transaction)
4	binding_type	String	20	Specify which type of binding WALLET: Zalopay Wallet CARD: ATM
5	binding_id	String	64	The id of binding has been confirmed in the Zalopay system.
6	pay_token	String	128	The public token is used when doing auto-debit.
7	server_time	Int64		Server timestamp in seconds.
8	merchant_user_id	String	128	The identifier field in bind request.
9	status	Int		1: Confirmed, 3: Cancelled, 4: Disabled
10	msg_type	Int		Type of message: 1: The user confirms an agreement 2: The user updates the agreement
11	zp_user_id	String	64	The identifier of Zalopay user per merchant app_id. Note: in case binding_type = WALLET
12	masked_user_phone	String	20	Masked user phone(Ex: masked_user_phone:"****6938") Note: in case binding_type = WALLET
13	masked_card_number	String	20	Masked user card number(Ex: "520032****5097") Note: in case binding_type = CARD
14	issuing_bank_logo	String	256	Url to get logo of issuing bank Note: in case binding_type = CARD
15	issuing_bank_name	String	64	Abbreviation name of issuing_bank(Ex: "Vietinbank") Note:in case binding_type = CARD

Example

Scenario 1: Binding Wallet

Request

{
  "app_id": "2688",
  "app_trans_id": "221011_09171700003",
  "req_date": "1665454943715",
  "mac": "ec57c1433b39fa86eb896b7e8505a3eb89577cd0f1f67d1fee558c75ffb15d77"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "sub_return_code": 1,
  "sub_return_message": "Success",
  "data": {
    "app_id": 2688,
    "app_trans_id": "221011_09171700003",
    "binding_type": "WALLET",
    "binding_id": "221011VvZq80GobDg8gTgXPeeLMaZMy",
    "pay_token": "YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY",
    "merchant_user_id": "NHAN",
    "zp_user_id": "bqdM80_MO1Dt1u9ESGrQPGEVHjza57mPMDZvPpQz_t4",
    "masked_user_phone": "****3801",
    "server_time": 1665454943,
    "status": 1,
    "msg_type": 1,
    "expiry_timestamp_in_ms": -62135596800000
  }
}

3.1.3. Binding Notification

Description

This API is implemented on the merchant site for receiving callbacks from Zalopay for agreements that have been confirmed or updated

Request Parameters

Parameter	Data Type	Max Length	Required	Description
data	JSON String	4096		Data callback
mac	String	256	64	Security string for request validation. macInput = data mac = HMAC(HmacSHA256, callbac Key, macInput) callback Key: key generated by Zalopay system for each merchant.
type	Int	256		Type of callback 1: Order 2: Agreement

Detail of data parameter

Parameter	Data Type	Max Length	Description
app_id	Int		The app id of the merchant
binding_data		2048	The binding data was sent in bind request.
app_trans_id	String	40	The merchant's unique id for the binding(TXID of binding transaction)
binding_type	String	20	Specify which type of binding - WALLET: Zalopay Wallet - CARD: ATM
binding_id	String	64	The id of binding has been confirmed in the Zalopay system
pay_token	String	128	The public token is used when doing paying
server_time	Int		Server timestamp in seconds
merchant_user_id	String	128	The identifier parameter in bind request
status	Int		1: Confirmed, 3: Cancelled, 4: Disabled
msg_type	Int		Type of message: 1: The user confirms an agreement 2: The user updates the agreement
zp_user_id	String	64	The identifier of Zalopay user per merchant app_id Note: in case binding_type = WALLET
masked_user_phone	String	20	Masked user phone(Ex: "****6938") Note: in case binding_type = WALLET
card_id	String	128	The unique identifier for a payment card Note: in case binding_type = CARD
masked_card_number	String	20	Masked user card number(Ex: "520032****5097") Note: in case binding_type = CARD
issuing_bank_logo	String	256	Url to get logo of issuing bank Note: in case binding_type = CARD
issuing_bank_name	String	64	Abbreviation name of issuing_bank (Ex: "Vietinbank") Note: in case binding_type = CARD

Response Fields

Parameter	Data Type	Max Length	Description
return_code	Int		1: Success 2: Failure
return_message	String	256	Description of return_code

3.1.4. Unbind

Description

This API will request to unbind an agreement in case a user doesn’t want to use the auto-debit feature.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	app_id	Int	Required		app-id provided by Zalopay, provided by Zalopay
2	identifier	String	Required	128	user's identifier on the merchant system, it can be a merchant user's id, phone number, email...
3	binding_type	String	Required	20	Specify which type of binding - WALLET: Zalopay Wallet - CARD: ATM
4	binding_id	String	Required	64	The ID of binding that the user wants to unbind.
5	req_date	Int64	Required		Current unix timestamp in milliseconds.
6	mac	String	Required	64	Security string macInput = app_id|identifier|binding_id|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Max length	Description
1	return_code	Int		1: Success, 2: Failure
2	return_message	String	256	Description of return code
3	sub_return_code	Int		Detail error code
4	sub_return_message	String	256	Detail error message

Example

Request

{
  "app_id": "2688",
  "identifier": "NHAN",
  "binding_type": "WALLET",
  "binding_id": "221011VvZq80GobDg8gTgXPeeLMaZMy",
  "req_date": "1665461267733",
  "mac": "5c48aa2af0b4348fbcb1ecf9f4c90295d4f757b1eb8caa1e7c55cb27c0e9c110"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "sub_return_code": 1,
  "sub_return_message": "Success"
}

3.2. Authorized Payment

3.2.1. Authorize

Description

This API is used to make an authorization transaction

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Maxlength	Description
1	app_id	Int	Required		The unique ID of the application will be provided after the merchant registered successfully with Zalopay.
2	app_trans_id	String	Required	40	Unique transaction ID of application (TXID of authorize transaction)
3	binding_type	String	Required	20	Specify which type of binding WALLET: Zalopay Wallet CARD: ATM(at present, just apply binding_type= WALLET)
4	identifier	String	Required	128	User's unique identifier on the merchant system. It can be the merchant user's id, phone number, email...
5	pay_token	String	Required	128	The public token of the payer. This value was returned after user binding success by binding notification or query binding API
6	amount	Int64	Required		The Amount of money will be charged.
7	item	JSON Array String	Required	2048	JSON array string describes order items.The required empty value is "[]"
8	embed_data	JSON String	Required	1024	JSON string includes additional information (used for promotion or customer support or reporting)The required empty value is "{}"
9	order_code	String	Optional		Type of order. The default value is GOODS. Supported list: GOODS, TRANSPORTATION, HOTEL, FOOD, P2P, TELCARD, BILLING
10	payment_id	String	Optional		This field is used for settlement goal
11	req_date	Int64	Required		The unix timestamp that the transaction was created in milliseconds. The different limit is 15 minutes.
12	mac	String	Required		Security string for request validation. macInput= app_id

Response Fields

No	Field name	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	status	Int	3: Authorizing, 4: Authorized
6	zp_trans_id	Long	The Zalopay transaction ID. The Merchant needs to save to use in reconciliation flow

Example

Request

{
  "amount": "50000",
  "app_id": "2688",
  "app_trans_id": "221011_09285100004",
  "embed_data": "{}",
  "identifier": "NHAN",
  "item": "[]",
  "mac": "352b5fae50691256a610ca26da7592fb5718b32c0028a30a51d6e6de8110a51f",
  "order_code": "TRANSPORTATION",
  "pay_token": "YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY",
  "payment_id": "",
  "req_date": "1665455331635"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "status": 4,
  "sub_return_code": 1,
  "sub_return_message": "Success",
  "zp_trans_id": 230725000950036
}

3.2.2. Capture

Description

This API is designed to capture an authorized transaction, and the amount captured must be either equal to or less than the authorized amount. Each authorized transaction can only be captured once.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Max Length	Mandatory	Description
1	app_id	Int		Required	Unique ID generated by Zalopay to identify each merchant's application.
2	app_trans_id	String	40	Required	TXID of the authorized transaction. This has the same value as app_trans_id in the request body of the /preauth/authorize API.
3	amount	Int64		Required	Amount to be captured in VND.
4	req_date	Int64		Required	Current unix timestamp in milliseconds.
5	mac	String	64	Required	Signature for request validation. mac = HMAC(Hmac_SHA256, macKey, macInput) macInput = app_id|app_trans_id|amount|req_date macKey: key generated by Zalopay system for each merchant's application

Response Body

No	Field name	Datatype	Description
1	return_code	Int	1: Success, 2: Failure
2	return_message	String	Description of return_code.
3	sub_return_code	Int	Detailed error code.
4	sub_return_message	String	Provide specific information for each response case.
5	status	Int	5: Capturing, 6: Captured
6	zp_trans_id	Long	The transaction id generated by Zalopay which associated to merchant's transaction (app_trans_id). Merchant needs to save it for use during the refund and reconciliation process.

Example

	Request	Response
Authorize	{"app_id":"2222","app_trans_id":"221011_09285100004","identifier":"user@merchant.com","pay_token":"YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","amount":"50000","item":"[]","embed_data":"{}","order_code":"TRANSPORTATION","payment_id":"","req_date":"1665455331635","mac":"352b5fae50691256a610ca26da7592fb5718b32c0028a30a51d6e6de8110a51f"}	{"return_code":1,"return_message":"Giao dịch thành công.","sub_return_code":1,"sub_return_message":"Giao dịch thành công.","status":4}
Capture	{"app_id":"2222","app_trans_id":"221011_09285100004","amount":"50000","req_date":"1665455571276","mac":"9a2d87e47228177a4620d8bd9bcc4f8df7cb34dee430b1bf0f188c3ceb567961"}	{"return_code":1,"return_message":"Giao dịch thành công.","sub_return_code":1,"sub_return_message":"Giao dịch thành công.","status":6,"zp_trans_id":221011000002836}

3.2.3. Cancel

Description

This API is used to cancel an authorizing/authorized request.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Description
1	app_id	Int	Required	app-id provided by Zalopay
2	app_trans_id	String	Required	TXID of the authorizing/authorized transaction.This has the same value as app_trans_id in the request body of /authorize API
3	req_date	Int64	Required	Current unix timestamp in milliseconds
4	description	String	Required	Cancel reason
5	mac	String	Required	Security string macInput = app_id|app_trans_id|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	status	Int	7: Cancelling, 8: Cancelled

Example

API	Request	Response
Authorize	{"amount":"100000","app_id":"2688","app_trans_id":"221011_09352400005","embed_data":"{}","identifier":"NHAN","item":"[]","mac":"6336df9d632d1db9c0f0b38f271c248282e15ce9f64e0ba9cdf75e1081f16008","order_code":"","pay_token":"YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","payment_id":"","req_date":"1665455724639"}	{"return_code":1,"return_message":"Success","status":4,"sub_return_code":1,"sub_return_message":"Success"}
Cancel	{"app_id":"2688","app_trans_id":"221011_09352400005","description":"Zalopay Cancel Payment Demo","mac":"9714db9fe9c02e04935715a015eb06d518e27667020c116661dc03700a261e98","req_date":"1665455925517"}	{"return_code":1,"return_message":"Success","status":8,"sub_return_code":1,"sub_return_message":"Success"}

3.2.4. Pay

Description

This API is used to make a direct payment transaction.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Maxlength	Description
1	app_id	Int	Required		The unique ID of the application will be provided after the merchant registered successfully with Zalopay.
2	app_trans_id	String	Required	40	Unique transaction ID of application (TXID of pay direct transaction)
3	binding_type	String	Required	20	Specify which type of binding WALLET: Zalopay Wallet CARD: ATM
4	identifier	String	Required	128	User's unique identifier on the merchant system. It can be the merchant user's id, phone number, email...
5	pay_token	String	Required	128	The public token of the payer. This value was returned after user binding success by binding notification or query binding API
6	amount	Int64	Required		The Amount of money will be charged.
7	item	JSON Array String	Required	2048	JSON array string describes order items.The required empty value is "[]"
8	embed_data	JSON String	Required	1024	JSON string includes additional information (used for promotion or customer support or reporting)The required empty value is "{}"
9	order_code	String	Optional		Type of order. The default value is GOODS. Supported list: GOODS, TRANSPORTATION, HOTEL, FOOD, P2P, TELCARD, BILLING
10	payment_id	String	Optional		This field is used for settlement goal
11	req_date	Int64	Required		The unix timestamp that the transaction was created in milliseconds. The different limit is 15 minutes.
12	mac	String	Required		Security string for request validation. macInput = app_id|app_trans_id|identifier|pay_token|amount|item|embed_data|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	status	Int	9: Paying, 10: Paid
6	zp_trans_id	Long	The Zalopay transaction ID. The Merchant needs to save to use in reconciling and refunding flow
7	verification_required	Bool	= true: require a verification from User
8	verification_url	String	The verification url for user perform confirmation

Example

success case

Request	Response
{"app_id": "2688","app_trans_id": "221011_09443000006","identifier": "NHAN","pay_token": "YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","amount": "150000","item": "[]","embed_data": "{}","order_code": "TRANSPORTATION","payment_id": "","req_date": "1665456270936","mac": "0f79892bdee67cd4ecd9b83298c503bfa648066a3feb07dc4e9ddc378d8b05a3"}	{"return_code": 1,"return_message": "Success","sub_return_code": 1,"sub_return_message": "Success","status": 10,"zp_trans_id": 221011000002992}

need verification case

Request	Response
{"app_id": "2688","app_trans_id": "221011_09443000006","identifier": "NHAN","pay_token": "YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","amount": "150000","item": "[]","embed_data": "{}","order_code": "TRANSPORTATION","payment_id": "","req_date": "1665456270936","mac": "0f79892bdee67cd4ecd9b83298c503bfa648066a3feb07dc4e9ddc378d8b05a3"}	{"return_code": 1,"return_message": "Success","sub_return_code": 1,"sub_return_message": "Success","status": 1,"verification_required": true,"verification_url": "https://gateway.zalopay.vn/verify_otp"}

3.2.5. Query Status

Description

This API is used to query the status of the transaction that has been executed by the authorize/amend/capture/cancel/pay API.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Description
1	app_id	Int	Required	app-id provided by Zalopay
2	app_trans_id	String	Required	TXID of the authorized or paid transaction.This has the same value as app_trans_id in the request body of /authorize API when you want to check the status of an authorized transactionThis has the same value as app_trans_id in the request body of /pay API when you want to check the status of a direct payment transaction
3	req_date	Int64	Required	Current unix timestamp in milliseconds
4	mac	String	Required	Security string macInput = app_id|app_trans_id|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Field name	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	zp_trans_id	String	The Zalopay transaction ID
6	status	Int	The statuses of the transaction 1: Created 2: Failed 3: Authorizing 4: Authorized 5: Capturing 6: Captured 7: Cancelling 8: Cancelled 9: Paying 10: Paid
7	refund_status	Int	Refund status 0: NoRefund 1: Refunded 4: Partially_Refunded

Example

Request	Response
{"app_id":"2688","app_trans_id":"221011_09443000006","mac":"3d44e8a5b350d0046536c587daf1d45e09e0e17e6ead9fde1b7e3fa13022ea3a","req_date":"1665456878501"}	{"refund_status":0,"return_code":1,"return_message":"Success","status":10,"sub_return_code":1,"sub_return_message":"Success","zp_trans_id":221011000002992}

3.2.6. Get Payable

Description

This API to check whether an user will be able to pay or not before paying or authorizing an order. Nevertheless, it's important to understand that the success of the Get_Payable API does not guarantee a 100% success rate for the Pay or Authorize APIs. Some fund sources, particularly those where our bank partners decline to disclose the user's account balance, consistently return successful responses for the Get_Payable API, but the Pay or Authorize APIs may still encounter failures if there are insufficient funds in the user's bank account.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	app_id	Int	Required	int	app-id provided by Zalopay
2	identifier	String	Required	128	user's identifier on the merchant system, it can be a merchant user's id, phone number, email...
3	pay_token	String	Required	128	The public token of the payer. This value was returned after user binding success by calling webhook or using /v2/agreement/query API
4	amount	Int64	Required	Int	The amount of the transaction you need to check max-pay-able
5	redirect_url	String	Optional	256	After the reform process finished, Zalopay auto-debit reform page will redirect to merchant via redirect URL with the reform result
6	req_date	Int64	Required	int	Current unix timestamp in milliseconds
7	mac	String	Required	64	Security string macInput = app_id|pay_token|identifier|amount|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Response Fields

No	Filed name	Datatype	Max length	Description
1	return_code	Int		1: Successful, 2: Failed
2	return_message	String	256	Error message
3	sub_return_code	Int		Detail error code
4	sub_return_message	String	256	Detail error message
5	data	Json Object Array		The array of channels which user can use to pay
6	reform_url	String		The url which is used to topup money in insufficient balance case or upgrade a(Open when sub_return_code = -1800 or -1010)
7	payable	Bool		If the user is able to pay

Example

Example 1:

Request	Response
{"amount":"1500000","app_id":"2688","identifier":"NHAN","mac":"dc777381a45918b92991c8bbcfc24028d928932315a9906e76a76e3e9bf0bb15","pay_token":"YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","req_date":"1665457162811"}	{"data":"[{"bank_code":"zp_app","channel":38},{"bank_code":"tktl","channel":44}]","payable":true,"return_code":1,"return_message":"Success","sub_return_code":1,"sub_return_message":"Success"}

Example 2:

Request	Response
{"amount":"1500000","app_id":"2688","identifier":"NHAN","mac":"dc777381a45918b92991c8bbcfc24028d928932315a9906e76a76e3e9bf0bb15","pay_token":"YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","redirect_url":"merchant://app","req_date":"1665457162811"}	{"reform_url":"https://zalo.me/qr/jp/7seo74pfsi?view=topup&app_id=2688&amount=100000&redirect_url=merchant%3A%2F%2Fapp","return_code":2,"return_message":"Failed","sub_return_code":-1010,"sub_return_message":"User has insufficient funds for payment"}

Example 3:

Request	Response
{"amount":"1500000","app_id":"2688","identifier":"NHAN","mac":"dc777381a45918b92991c8bbcfc24028d928932315a9906e76a76e3e9bf0bb15","pay_token":"YMVKZWQWNJCTM2YZOC0ZNZZHLTHLNMQTOTJMOGVJNZJJODIY","redirect_url":"merchant://app","req_date":"1665457162811"}	{"reform_url":"https://zalo.me/qr/jp/7seo74pfsi?view=kyc&app_id=2688&redirect_url=merchant%3A%2F%2Fapp","return_code":2,"return_message":"Failed","sub_return_code":-1800,"sub_return_message":"Payment limit exceeded according to KYC"}

3.2.7. Create

Description

This API is used to create an order that pay by card (and can automatically link)

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Maxlength	Description
1	app_id	Int	Required		The unique ID of the application will be provided after the merchant registered successfully with Zalopay.
2	app_trans_id	String	Required	40	Unique transaction ID of application (TXID of pay direct transaction)
3	identifier	String	Required	128	User's unique identifier on the merchant system. It can be the merchant user's id, phone number, email...
4	amount	Int64	Required		The Amount of money will be charged.
5	item	JSON Array String	Required	2048	JSON array string describes order items.The required empty value is "[]"
6	embed_data	JSON String	Required	1024	JSON string includes additional information (used for promotion or customer support or reporting)The required empty value is "{}"
7	order_code	String	Optional		Type of order. The default value is GOODS. Supported list: GOODS, TRANSPORTATION, HOTEL, FOOD, P2P, TELCARD, BILLING
8	payment_id	String	Optional		This field is used for settlement goal
9	bank_code	String	Required		Bank code of request (at present, just apply bank_code=ATM)
10	callback_url	String	Optional		Zalopay will notify to this URL only when the payment is success; If not provided, the default app Callback URL will be used.
11	req_date	Int64	Required		The unix timestamp that the transaction was created in milliseconds. The different limit is 15 minutes.
12	mac	String	Required		Security string for request validation. macInput = app_id|app_trans_id|identifier|amount|item|embed_data|req_date mac = HMAC(HmacSHA256, macKey, macInput) macKey: key generated by Zalopay system for each merchant.

Specific embed_data fields

Name	DataType	Format	Description	Example
binding_info	JSON String	{"field_name": "value"}	binding_info must have fields as bellow:agree_to_link: the user has agreed to save the payment information for the next timebinding_type:This parameter specifies the type of bindingcallback_url:Zalopay tokenization system will notify Binding Token to merchant system via this URL.	"binding_info":"{"agree_to_link":true,"binding_type":"CARD","callback_url":"https://merchant.com/binding_result/?"}"}

Response Fields

No	Field name	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	order_url	String	Used to open Zalopay Gateway page for user input card info and submit
6	zp_trans_token	String	Transaction token

Example

Request	Response
{"amount":"150000","app_id":"2688","app_trans_id":"221011_09443000006","bank_code":"ATM","embed_data":"{}","identifier":"NHAN","item":"[]","mac":"0f79892bdee67cd4ecd9b83298c503bfa648066a3feb07dc4e9ddc378d8b05a3","order_code":"TRANSPORTATION","payment_id":"","req_date":"1665456270936"}	{"return_code":1,"return_message":"Success","status":"https://gateway.zalopay.vn/openinapp?order=eyJ6cHRyYW5zdG9rZW4iOiJBQ0hleHFtTElpQk84c1p6ZmR6S21Ra1EiLCJhcHBpZCI6MTAwMzN9","sub_return_code":1,"sub_return_message":"Success","zp_trans_token":"ACHexqmLIiBO8sZzfdzKmQkQ"}

3.3. Refund

3.3.1. Refund

Description

API refunds the transaction's amount that has been successfully paid/captured via Zalopay.

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	m_refund_id	String	Required	45	• Merchant must be generate merchant own transaction code when submit refund requirement. • Format: yymmdd_appid_xxxxxxxxxx
2	app_id	Int	Required		Merchant app_id, which was provided by Zalopay when registering.
3	app_trans_id	String	Required	15	• TXID of the authorized or paid transaction.
4	amount	Long	Required		Refund amount for users
5	req_date	Long	Required	13	• Time to refund (unix timestamp in millisecond). • The time of making the refund, is calculated in milliseconds
6	mac	String	Required		Authenticate information (See how to create authenticate information) hmac_algorithm: is a security method registered by Merchant with Zalopay, the default is HmacSHA256 macinput = app_id +"|"+m_refund_id + "|"+app_trans_id +"|"+ amount +"|"+ description +"|"+req_date mac = HMAC(hmac_algorithm, macKey, macinput) macKey: key generated by Zalopay system for each merchant.
7	description	String	Required	100	Refund reason

Response Fields

No	Params	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return code
3	sub_return_code	Int	Detail error code
4	sub_return_message	String	Detail error message
5	refund_status	Int	1: Refunded 3:Refunding
6	refund_id	Long	Zalopay refund's transaction code, need to save for cross-check then

Example

Request

{
  "app_id": "2688",
  "m_refund_id": "221011_2688_10074200009",
  "zp_trans_id": "221011000002992",
  "amount": "150000",
  "req_date": "1665457662550",
  "mac": "a2adcbb09a2ec15c143eabe887a8f21bcc0f811f0764cd939354eba5b8c97d4f",
  "description": "Zalopay Demo - Refund TransID 221011000002992",
  "mac_key": "xmMs1kVGz4iItUFykGqvVpCi2eWNkw46"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "sub_return_code": 1,
  "sub_return_message": "Success",
  "refund_status": 1,
  "refund_id": 221011000100053
}

3.3.2. Query Refund

Description

API allows merchants to query the refund status of a refund transaction

Sequence

Integration

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

Request Parameters

No	Params	Datatype	Mandatory	Max length	Description
1	app_id	Int	Required		app_id provided by Zalopay
2	m_refund_id	String	Required	45	• The transaction code, which was generated by merchant when querying refund transaction. • Format: yymmdd_appid_xxxxxxxxxx
3	req_date	Long	Required		The time call API (timestamp in millisecond)
4	mac	String	Required		= HMAC(hmac_algorithm, key1, app_id+"|"+m_refund_id+"|"+req_date)

Response Fields

No	Params	Datatype	Description
1	return_code	Int	1: Successful, 2: Failed
2	return_message	String	Description of return_code
3	sub_return_code	Int	Error code detail
4	sub_return_message	String	Description of sub_return_code
5	refund_status	Int	The statuses of the refund transaction 1: Refunded 2: Refund_Failed 3: Refunding
6	refund_id	Long	Zalopay refund's transaction code, need to save for cross-check then

Example

Request

{
  "app_id": "2688",
  "m_refund_id": "221011_2688_10074200009",
  "req_date": "1665458480710",
  "mac": "58353dd94418ade5b67825ea4a770c3dc8943875c18951ae3aaadae07809d4d6"
}

Response

{
  "return_code": 1,
  "return_message": "Success",
  "sub_return_code": 1,
  "sub_return_message": "Success",
  "refund_status": 1,
  "refund_id": 221011000100053
}

4. Error Code Information

4.1. Error Code

return_code value

Value	Description
1	Successful
2	Failed
3	Processing

sub_return_code

sub_return_code	Short Description	Meaning	Type
1	SUCCESS	Success	Successful
-1	UNKNOWN	Unknown error	System or User Error
-54	TIME_INVALID	req_date param of request is not unix timestamp in milliseconds format or more than 15 minutes difference from current time	Merchant Error
-68	DUPLICATE_APPS_TRANS_ID	Duplicate transaction	Merchant Error
-101	ORDER_NOT_EXISTS	Order not exists	Merchant Error
-102	TRANS_IS_NOT_ALLOWED	Ex: Call capture a transaction which has been cancelled; or capture amount exceeds authorized amount	Merchant Error
-401	ILLEGAL_DATA_REQUEST	Request param is illegal	Merchant Error
-402	ILLEGAL_APP_REQUEST	AppID is invalid	Merchant Error
-403	ILLEGAL_SIGNATURE_REQUEST	Wrong mac (wrong mac key or param to create mac)	Merchant Error
-500	SYSTEM_ERROR	Zalopay System Error	System Error
-1009	USER_HAS_BEEN_LOCKED	User account is locked	User Error
-1010	USER_CANNOT_PAY	The user account has no source of funds eligible for payment	User Error
-1011	PERMISSION_DENIED	Token is invalid/unlinked/expired and user needs to relink.	User Error
-1012	USER_IS_NOT_ELIGIBLE_FOR_PAYMENT	User is not eligible for payment due to risk rule, etc	User Error
-1013	PAYMENT_AMOUNT_EXCEED_LIMIT	The Order amount for payment exceeds the limit	User Error
-1800	USER_EXCEED_KYC_LIMIT	User has exceeded the limit according to KYC requirement	User Error
-1801	SYSTEM_IS_MAINTENANCE	Zalopay System is in maintenance	System Error

4.2. Error Code mapping with scenarios

API	Scenario	sub_return_code	sub_return_message
All	Required parameter is missing or parameter value is invalid	-401	Illegal request data
All	App ID is not allowed	-402	Unknown app
All	Wrong mac value	-403	Wrong signature
All	req_date param is not unix timestamp in milliseconds format or more than 15 minutes difference from current time	-54	Invalid request date
All	Zalopay system is in maintenance	-1801	System maintenance
All	Internal error of Zalopay system	-500	System internal error
Binding	app_trans_id is same as the previous one	-68	Duplicate app trans id
Unbind	Using BindingID does not exist	-101	Binding does not exist
Query Binding	Query BindingID does not exist	-101	Binding does not exist
Get Payable, Authorize or Pay	User account has been locked	-1009	User account has been locked
Get Payable, Authorize or Pay	The user account has no eligible source of funds eligible for payment	-1010	User has insufficient funds for payment
Get Payable, Authorize or Pay	Payment token is invalid/unlinked/expired	-1011	Permission denied
Get Payable, Authorize or Pay	User is not eligible for payment due to risk rule, etc	-1012	User is not eligible for payment
Get Payable, Authorize or Pay	The amount exceeds the maximum limit set by the user for this app	-1013	Payment limit exceeded
Get Payable, Authorize or Pay	User has exceeded the limit according to KYC requirement	-1800	Payment limit exceeded according to KYC
Authorize or Pay	app_trans_id is same as the previous one	-68	Duplicate merchant transaction id
Capture or Cancel	The requested transaction has not been authorized before	-101	Transaction does not exist
Capture or Cancel	The requested transaction is not in authorized state	-102	Transaction not allowed
Query	The requested transaction does not exist	-101	Transaction does not exist
Refund	m_refund_id param is not prefixed with format yyMMdd of the current day (GMT+7) & App ID	-92	Invalid merchant transaction id
Refund	The original transaction does not exist	-101	Transaction does not exist
Refund	+ The original transaction is not in captured or paid state	-102	Transaction not allowed
Refund	+ The capture amount exceeds the authorized amount	-102	Transaction not allowed
Refund	+ Refund amount is greater than payment amount	-102	Transaction not allowed
Refund	+ Refund time limit has passed	-102	Transaction not allowed
Query Refund	The requested transaction does not exist	-101	Transaction does not exist