NAV

POS - QuickPay

Giới thiệu Demo Hướng dẫn tích hợp Đặc tả API

Sequence Flow

Đặc tả API#

Environment Method Endpoint
Sandbox POST https://sb-openapi.zalopay.vn/v2/quick_pay
Real POST https://openapi.zalopay.vn/v2/quick_pay

application/x-www-form-urlencoded

application/json

application/xml

Dữ liệu truyền vào api#

Tham số Kiểu dữ liệu Kích thước Bắt buộc Ý nghĩa
app_id int Định danh cho ứng dụng đã được cấp bởi ZaloPay.
app_user String 50 Thông tin người dùng như id/username... Dùng tên ứng dụng nếu không định danh được.
app_time long Thời điểm tạo đơn hàng (current unix timestamp in milisecond).
amount long Giá trị của đơn hàng theo VND
app_trans_id String 40 Mã giao dịch của đơn hàng bắt đầu theo format yymmdd-Mã đơn hàng thanh toán.

Lưu ý: Với yymmdd phải đúng TimeZone Vietnam (GMT+7) (Vì các giao dịch đối soát theo ngày giờ Việt Nam).

embed_data String 1024 Dữ liệu riêng của đơn hàng. Dùng "{}" nếu rỗng.
item String 1024 Item của đơn hàng, do Merchant tự định nghĩa. Dùng "[]" nếu rỗng.
mac String Thông tin chứng thực của đơn hàng. Địa chỉ IP của user
payment_code String Được scan từ ứng dụng ZaloPay, được mã hóa bằng Public Key do ZaloPay cấp =RSA(paymentCodeRaw, publicKey)
description String 100 Thông tin mô tả về đơn hàng. Sẽ hiển thị lúc thanh toán ZaloPay
callback_url String ZaloPay sẽ thông báo trạng thái thanh toán của đơn hàng khi thanh toán hoàn tất; callback_url được gọi để thông báo kết quả thanh toán thất bại hoặc thành công.

Nếu không được cung cấp, callback_url mặc định của ứng dụng sẽ được sử dụng.

redirect_url String Redirect về url này sau khi thanh toán (override redirect url lúc đăng ký app với ZaloPay)
device_info String 256 Chuỗi JSON mô tả thông tin của thiết bị
currency String Đơn vị tiền tệ. Mặc định là VND
title String 256 Tiêu đề đơn hàng.
userIP String Địa chỉ IP của user

Một số trường đặc biệt của embed_data#

Tên
Kiểu dữ liệu Định dạng Mô tả Ví dụ
redirecturl String URL Redirect về url này sau khi thanh toán trên cổng ZaloPay (override redirect url lúc đăng ký app với ZaloPay) {"redirecturl": "https://docs.zalopay.vn/result"}
columninfo JSON String {"column_name": "value"} Thêm thông tin hiển thị ở phần Quản lý giao dịch chi tiết trên Merchant site, nếu cột chưa tồn tại cần vào phần Cài đặt hiển thị dữ liệu để cấu hình {"columninfo": "{\"branch_id\": \"HCM\",\"store_id\": \"CH123\",\"store_name\": \"Saigon Centre\",\"mc_campaign_id\": \"FREESHIP\"}"}
promotioninfo JSON String {"campaigncode":"code"} Dùng để triển khai chương trình khuyến mãi {"promotioninfo": "{\"campaigncode\":\"blackfriday\"}"}
zlppaymentid String - Mã thông tin thanh toán.
- Chỉ truyền khi đối tác cần nhận tiền đối soát về nhiều tài khoản khác nhau.
- Hệ thống ZaloPay sẽ tạo ra một mã Thanh toán (tương ứng với mỗi Tài khoản ngân hàng đối tác cung cấp) và gởi lại cho đối tác thiết lập.
{"zlppaymentid": "P4201372"}

Tạo thông tin chứng thực#

mac = HMAC(hmac_algorithm, key1, hmac_input)

Trong đó:

Tham số api trả về#

Tham số Kiểu dữ liệu Ý nghĩa
return_code int

1: Giao dịch thành công

2: Lỗi

3: Đang xử lý, kiểm tra trạng thái đơn hàng bằng API truy vấn trạng thái đơn hàng

return_message String Thông tin lỗi
sub_return_code int Mã lỗi từ đối tác
sub_return_message String Mô tả chi tiết mã trạng thái từ đối tác
is_processing boolean true: Đang xử lý
false: Kết thúc giao dịch
zp_trans_id long Mã giao dịch của ZaloPay

Code mẫu#

/**
 * .Net core 2.1.505
 */
using System;
using System.Text;
using System.Collections.Generic;
using System.Threading.Tasks;
using ZaloPay.Helper; // HmacHelper, RSAHelper, HttpHelper, Utils (tải về ở mục DOWNLOADS)
using ZaloPay.Helper.Crypto;
using Newtonsoft.Json; // https://www.newtonsoft.com/json

namespace ZaloPayExample
{
    class Program
    {
        static string app_id = "2553";
        static string key1 = "PcY4iZIKFCIdgZvA6ueMcMHHUbRLYjPL";
        static string quickPayUrl = "https://sb-openapi.zalopay.vn/v2/quick_pay";
        static string rsaPublicKey = "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAMsHyik+FG0NjTxCu3yHTo8EczhRIlZA6Y1IE0yTGEOwfqN4hD2prbrO0HxaWrVBUjHholVyhkmGpMm56vGHQ7UCAwEAAQ==";

        static async Task Main(string[] args)
        {
            var transid = Guid.NewGuid().ToString(); 
            var embed_data = new { merchantinfo = "embed_data123" };
            var items = new []{
                new { itemid = "knb", itemname = "kim nguyen bao", itemprice = 198400, itemquantity = 1 }
            };
            var paymentCodeRaw = "174830909300000096"; 
            var param = new Dictionary<string, string>();

            param.Add("app_id", app_id);
            param.Add("app_user", "demo");
            param.Add("app_time", Utils.GetTimeStamp().ToString());
            param.Add("amount", "1000");
            param.Add("app_trans_id", DateTime.Now.ToString("yyMMdd") + "_" + transid);
            param.Add("embed_data", JsonConvert.SerializeObject(embed_data));
            param.Add("item", JsonConvert.SerializeObject(items));
            param.Add("description", "ZaloPay QickPay Demo");
            param.Add("payment_code", RSAHelper.Encrypt(paymentCodeRaw, rsaPublicKey)); 
            param.Add("order_code", "GOODS");

            var data = app_id + "|" + param["app_trans_id"] + "|" + param["app_user"] + "|" + param["amount"] + "|" 
                + param["app_time"] + "|" + param["embed_data"] + "|" + param["item"] + "|" + paymentCodeRaw;
            param.Add("mac", HmacHelper.Compute(ZaloPayHMAC.HMACSHA256, key1, data));

            var result = await HttpHelper.PostFormAsync(quickPayUrl, param);

            foreach(var entry in result) {
                Console.WriteLine("{0} = {1}", entry.Key, entry.Value);
            }
        }
    }
}
Không tìm thấy kết quả phù hợp