Payment Gateway

Overview

Zalopay Gateway is one of the leading payment gateways in Vietnam, featuring a variety of payment methods and top security commitment, creating a convenient and safe payment experience for both users and customers. enterprise. Here are some important features of the Zalopay payment gateway:

Diverse payment methods: Zalopay Gateway provides payment methods, from Zalopay Wallet, ATM Card, Internet Banking, Visa Card, VietQR to Apple Pay. This diversity helps users choose payment methods that suit their personal needs and is convenient for businesses when expanding business opportunities.
User information security: Certified to international standards for information security (PCI DSS and ISO 27001) by independent and reputable organizations. User payment information is encrypted with high safety and reliability.
Convenience for Businesses: The process of integrating Zalopay Gateway into a business's payment system is designed to be simple and flexible. The easy-to-use API interface helps businesses integrate quickly, expand reach and optimize online payment processes.
Multifunctional Zalopay QR - Smart bridge between customers and services: Multifunctional Zalopay QR (VietQR) not only helps users pay quickly but also brings great benefits to businesses. The versatile use of Zalopay QR helps optimize the payment process and connect customers with the business's products and services effectively.
Apple Pay - Easy payment for iOS users: Zalopay integrates Apple Pay into the payment gateway, creating convenient payment opportunities for users using iOS devices. This not only expands the customer base but also enhances the payment experience for the Apple user community.
Zalopay Gateway is not just a payment gateway, but a smart integrated ecosystem, combining diverse payment methods, solid security and easy integration. This not only creates a modern payment environment but also brings many business opportunities for businesses and convenience for users.
In the next sections, we will guide you step by step to integrate Zalopay Payment Gateway into the payment system.

Preconditions

Before you begin, make sure the following are in place for a smooth integration:

• Successfully registered a merchant account and obtained app_id, mac_key, callback_key information from Zalopay.
• Understand the usage and specifications of the following APIs: Create Order API, Query Order API
• Concept of secure data transmission.

How it works

Noted

Concept	Describe
User	Users make purchases and payments
MerchantSite	Merchant Web Application
MerchantServer	Merchant Backend System
ZalopayGateway	Zalopay payment gateway
ZalopayServer	Backend system of Zalopay

The detailed operation flow is as follows

1. MerchantSite displays payment methods and payment buttons.
2. User purchases from MerchantSite, selects payment method and clicks on the payment button.
3. MerchantSever calls the Create Order API to create a new order via ZalopayServer.
4. MerchantSite redirects to the ZalopayGateway page based on the order_url received from the response upon successful order creation.
5. User completes payment on ZalopayGateway.
6. ZalopayGateway redirects back to MerchantSite.
7. MerchantServer receives payment results.
8. Merchant Site displays payment result notification to User.

Integration

This section focuses on how to integrate Zalopay Payment Gateway. The process includes the following steps:

1. Display payment forms on your page
2. Use the Create Order API to create an order
3. Navigate users to Zalopay Payment Gateway
4. Handle and display transaction results using callback or Query Order API

Step 1. Display payment methods

When the User performs the order payment operation, the MerchantSite interface needs to display Zalopay payment forms such as: Zalopay Wallet, Visa/Master/JCB Card, ATM Card, Apple Pay, Multifunctional Zalopay QR according to the reference specifications as below:

Step 2. Send order creation request

• After the User clicks Pay, MerchantSite sends a request to create a payment order (Create Order) to MerchantServer
  
• Merchant Server will call Create Order API to Zalopay Server.
  
• This is an example of a request to create an order and a response received:

Request:

{
  "amount": "10000",
  "app_id": "2553",
  "app_time": "1703664998490",
  "app_trans_id": "231227_2553_1703664997117",
  "app_user": "demo",
  "bank_code": "",
  "description": "Test",
  "embed_data": {
    "preferred_payment_method": [
      "vietqr"
    ]
  },
  "item": [],
  "mac": "0336b57f74209f3b944c88b8fc8c878ae518d20b7e88763fb2ff9e14e6c3cac5"
}

Response:

{
  "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",
  "zp_trans_token": "AC5TYXNLtPgMkO-IBA2_VoBA",
  "order_url": "https://qcgateway.Zalopay.vn/openinapp?order=eyJ6cHRyYW5zdG9rZW4iOiJBQzVUWVhOTHRQZ01rTy1JQkEyX1ZvQkEiLCJhcHBpZCI6MjU1M30=",
  "order_token": "AC5TYXNLtPgMkO-IBA2_VoBA",
  "qr_code": "00020101021226520010vn.Zalopay0106180005020300103175672745585088359438620010A00000072701320006970454011899ZP23361O002489830208QRIBFTTA5204739953037045405100005802VN622108175672745585088359463044F20"
}

Note: How to use the bank_code and preferred_payment_menthod parameters in the Create Order API, corresponding to each payment option.

bank_code	preferred_payment_method	Information transmission content	The results are displayed on the payment gateway page	Note
Empty ("")	[]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": []}"	List of all supported forms and banks (ATM, CC, Zalopay, Zalopay QR multifunction, Apple Pay...)	Image description 1
Empty ("")	["domestic_card", "account"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"domestic_card\", \"account\"]}"	List of all supported Banks, users select and enter corresponding ATM card or Bank account information	Image description 2
Empty ("")	["Zalopay_wallet"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"Zalopay_wallet\"]}"	Display Zalopay QR code to pay with Zalo/Zalopay	Image description 3
Empty ("")	["vietqr"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"vietqr\"]}"	Display multi-functional Zalopay QR to pay with Banking and Zalo/Zalopay applications	Image description 4
Empty ("")	["international_card"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"international_card\"]}"	The form displays for entering credit card information	Image description 5
Empty ("")	["applepay"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"applepay\"]}"	Form displays for selecting Apple Pay method	Image description 6
BankCode ATM (VTB, VCB,...)	[]	"bank_code": "specific bank code", "embed_data": "{\"preferred_payment_method\": []}"	The form to enter card information of the corresponding bank Merchant uses the Getlistmerchantbanks API to get the specific bankcode value. (**) Use the API to get the list of supported banks here	Image description 7

#Image description 1

#Image description 2

#Image description 3

#Image description 4

#Image description 5

#Image description 6

#Image description 7

Step 3. Process and display transaction results

When the buyer completes payment, Zalopay Payment Gateway will redirect back to the merchant's web application/app according to the redirecturl information at application registration or the redirecturl value at the order creation step. And the next step is to check the order status via callback or Query Order API.

Handle callbacks from ZalopayServer

After the User completes the payment steps on ZalopayGateway, if the user is successfully deducted, ZalopayServer will return (callback/notify) payment status information to MerchantServer according to callback_url when registering the application or callback_url value at the order creation step. row

Query order status

When the user makes a successful payment, ZalopayServer will call a callback to MerchantServer. However, callbacks may be missed due to Network/Service Unavailable/... issues. For the best user experience, Merchants need to proactively query order status every 1 minute until a callback is received or Order payment deadline expires.

Navigate (redirect) to the Merchant system

After the user completes payment, ZalopayGateway will redirect to the Merchant's results display page (according to the redirecturl that Merchant has provided to Zalopay).

Data is passed into the query string when Zalopay redirects to the Merchant's page

Param	Describe
appid	app_id information of the order
apptransid	app_trans_id information of the order
pmcid	Payment channel information
bankcode	bank_code information
amount	Order value
discountamount	Discount value
status	Status code
checksum	Used to check if the redirect is valid or not. Check for valid hmac: HMAC(hmac_algorithm, key2, appid + "\|"+ apptransid +"\|"+ pmcid +"\|"+ bankcode +"\|"+ amount +"\|"+ discountamount +"\|"+ status)

For example: https://www.pay.abc.com/result/?amount=10000&discountamount=0&appid=165000&checksum=a179866d5dfc98d486ed51f5e53113776d2eb387049f07bd17e31c95ef5aaf3e&apptransid=231227_165000_1703670602601&pmcid=38&bankcode=&status=1

Note: When receiving a valid redirect, the Merchant needs to check whether the callback has been received or not. If not, the Merchant uses the API to query the order's payment status to get the final result.