Skip to main content

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.

Key Benefits

For Businesses:

  • All-in-one payment solution for websites and sales apps, with versatile QR code integration to attract more customers.
  • Seamless Zalopay integration diversifies payment channels and enhances the overall shopping experience.

For Customers:

  • Multiple payment methods to suit every preference.
  • Fast, flexible, and secure transactions, ensuring peace of mind with every payment.

How it works

Flow diagram:

Payment flow

Flow explanation:
Step 1: The customer initiates payment through the Zalopay Payment Gateway.
Step 2: The merchant creates an order via the Zalopay system for the customer to proceed with payment.
Step 3: After verifying the merchant information, Zalopay returns a payment link (order_url).
Step 4: The merchant redirects the customer to the Zalopay Payment Gateway using the payment link (order_url).
Step 5: The Zalopay Payment Gateway displays the order details and requests the customer to make a payment.
Step 6: The customer selects a payment method and completes the transaction.
step 7: The Zalopay Payment Gateway processes the payment, returns the result, and redirects back to the merchant’s page.
Bước 8: The merchant receives the payment result and displays the payment status notification to the customer.

Integration guide

This section provides a basic guide for businesses to integrate the Zalopay Payment Gateway using the APIs provided by Zalopay. The integration process includes the following key steps:

  • Display available payment methods on the business’s system.
  • Send an order creation request to Zalopay.
  • Redirect the customer to the Zalopay Payment Gateway.
  • Handle the payment result.

1. Display available payment methods

When a customer proceeds to pay for an order, the checkout interface on the merchant’s system must display the available Zalopay payment methods, such as: Zalopay App, Visa/Master/JCB Cards, ATM Cards, and Zalopay QR multi-function; the display format should follow the reference guidelines as shown below:

Payment flow

2. Send order creation request

After the customer selects a payment method, the merchant sends a request to create an order using the Create order API provided by the Zalopay system.

Below is an example of an order creation request and the corresponding response:

Request

{
"app_id": 123015,
"app_time": "1703664998490,
"app_trans_id": "231227_123015_1703664997117",
"app_user": "demo",
"bank_code": "",
"description": "Test",
"amount": 10000,
"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"
}

3. Redirecting the Customer to Zalopay Gateway

The merchant redirects the customer to the Zalopay Gateway using the order_url value received in the response after a successful order creation request. The merchant can configure Zalopay Gateway to display the interface in one of the following modes:

Let the Customer Choose a Payment Method

With this option, Zalopay Gateway will display a list of all supported payment methods, allowing the customer to choose one to complete the payment.

The payment methods provided by Zalopay include:

  • Domestic ATM Cards
  • Credit/Debit Cards
  • Bank Transfer via Zalopay QR multi-function (VietQR)
  • Zalopay QR Payment via Zalo/Zalopay App
  • QR Payment via Zalo/Zalopay App with Postpaid Account as the prioritized payment source

Depending on the service agreement between Zalopay and the merchant, only the contracted payment methods will be displayed.

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": []}"

Payment flow

Let the Customer payment Zalopay QR multi-function (VietQR)

With this option, Zalopay Gateway will display Zalopay QR multi-function to pay with Banking and Zalopay/Zalopay in Zalo applications.

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": [\"vietqr\"]}"

Payment flow

Let the Customer payment Credit/Debit Cards

With this option, Zalopay Gateway will display the form for entering credit card information.

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": [\"international_card\"]}"

Payment flow

Let the Customer payment ATM Cards

With this option, Zalopay Gateway will display the form for entering ATM card or Bank account information.

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": [\"domestic_card\",\"account\"]}"

Payment flow

Let the Customer payment Zalopay QR

With this option, Zalopay Gateway will display Zalopay QR to pay with Zalopay/Zalopay in Zalo applications.

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": [\"zalopay_wallet\"]}"

Payment flow

Let the Customer payment Zalopay QR by prioritize Buy now pay later

With this option, Zalopay Gateway will display Zalopay QR to pay with Zalopay/Zalopya in Zalo applications and the user's SOF will prioritize Buy now pay later (BNPL).

Note: For this option, use the parameters bank_code and preferred_payment_method when sending the order creation request, as shown below:

  • "bank_code": ""
  • "embed_data": "{\"preferred_payment_method\": [\"bnpl\"]}"

Payment flow

4. Processing the payment result

Once the buyer completes the payment, the Zalopay Gateway will redirect back to the merchant’s web/app based on the redirecturl provided during application registration or the redirecturl specified in the order creation step.

Handle callbacks from Zalopay Server

After the customer completes the payment steps on the Zalopay Gateway, if the payment is successful, the Zalopay system will return a payment status notification (callback/IPN) to the merchant.

Query order status

When the user completes a successful payment, the Zalopay system will trigger a callback (IPN) to the merchant. However, the callback may sometimes be missed due to issues such as network errors, service unavailability, etc. To ensure the best user experience, the merchant should actively query the order status using the Order Query API at a frequency of once per minute, until the callback is received or the order payment time limit expires.

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

ParamDescribe
appidapp_id information of the order
apptransidapp_trans_id information of the order
pmcidPayment channel information
bankcodebank_code information
amountOrder value
discountamountDiscount value
statusStatus code
checksumUsed to check if the redirect is valid or not. Check for valid hmac: HMAC(hmac_algorithm, callback key, appid + "\|"+ apptransid +"\|"+ pmcid +"\|"+ bankcode +"\|"+ amount +"\|"+ discountamount +"\|"+ status)

For example: https://www.merchant-server.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.