Cổng thanh toán

Tổng quan

Zalopay Gateway là một trong những cổng thanh toán hàng đầu tại Việt Nam, nổi bật với đa dạng các phương thức thanh toán và cam kết bảo mật hàng đầu, tạo ra một trải nghiệm thanh toán thuận tiện và an toàn cho cả người dùng và doanh nghiệp. Dưới đây là một số đặc điểm quan trọng của cổng thanh toán Zalopay:

Đa dạng phương thức thanh toán: Zalopay Gateway cung cấp các phương thức thanh toán, từ Ví Zalopay, Thẻ ATM, Internet Banking, Thẻ Visa, VietQR đến Apple Pay. Sự đa dạng này giúp người dùng lựa chọn phương thức thanh toán phù hợp với nhu cầu cá nhân và thuận lợi cho doanh nghiệp khi mở rộng cơ hội kinh doanh.
Bảo mật thông tin người dùng: Được chứng nhận các tiêu chuẩn quốc tế về bảo mật thông tin (PCI DSS và ISO 27001) bởi các tổ chức độc lập và uy tín. Thông tin thanh toán của người dùng được mã hóa với độ an toàn và tin cậy cao.
Thuận tiện cho Doanh nghiệp: Quá trình tích hợp Zalopay Gateway vào hệ thống thanh toán của doanh nghiệp được thiết kế để đơn giản và linh hoạt. Giao diện API dễ sử dụng giúp doanh nghiệp tích hợp nhanh chóng, mở rộng khả năng tiếp cận và tối ưu hóa quy trình thanh toán trực tuyến.
Zalopay QR đa năng - Cầu nối thông minh giữa khác hàng và dịch vụ: Zalopay QR đa năng (VietQR) không chỉ giúp người dùng thanh toán nhanh chóng mà còn mang lại lợi ích lớn cho doanh nghiệp. Việc sử dụng Zalopay QR đa năng giúp tối ưu hóa quá trình thanh toán và kết nối khách hàng với sản phẩm và dịch vụ của doanh nghiệp một cách hiệu quả.
Apple Pay - Thanh toán dễ dàng cho người dùng iOS: Zalopay tích hợp Apple Pay vào cổng thanh toán, tạo cơ hội thanh toán tiện lợi cho người dùng sử dụng thiết bị iOS. Việc này không chỉ mở rộng đối tượng khách hàng mà còn tăng cường trải nghiệm thanh toán cho cộng đồng người dùng Apple.
Zalopay Gateway không chỉ là cổng thanh toán, mà là một hệ sinh thái tích hợp thông minh, với việc kết hợp giữa đa dạng phương thức thanh toán, bảo mật vững chắc và tích hợp dễ dàng. Điều này không chỉ tạo ra một môi trường thanh toán hiện đại mà còn mang lại nhiều cơ hội kinh doanh cho doanh nghiệp và sự thuận lợi cho người dùng.
Trong các phần tiếp theo, chúng tôi sẽ hướng dẫn bạn từng bước để tích hợp Cổng thanh toán Zalopay vào hệ thống thanh toán.

Tiền điều kiện

Trước khi bạn bắt đầu, hãy đảm bảo các công việc sau được thực hiện để tích hợp suôn sẻ:

• Đã đăng ký tài khoản merchant thành công và có được thông tin app_id, mac_key, callback_key từ Zalopay.
• Hiểu cách sử dụng và đặc điểm kỹ thuật của các API sau: Create Order API, Query Order API
• Khái niệm truyền dữ liệu an toàn.

Cách hoạt động

Chú thích

Khái niệm	Mô tả
User	Người dùng mua hàng và thanh toán
MerchantSite	Ứng dụng Web của Merchant
MerchantServer	Hệ thống Backend của Merchant
ZalopayGateway	Cổng thanh toán Zalopay
ZalopayServer	Hệ thống Backend của Zalopay

Luồng hoạt động chi tiết như sau

1. MerchantSite hiển thị các phương thức thanh toán và nút thanh toán.
2. User mua hàng MerchantSite tiến hành chọn phương thức thanh toán và nhấp vào nút thanh toán.
3. MerchantSever gọi API Create Order để tạo một đơn hàng mới qua ZalopayServer.
4. MerchantSite chuyển hướng đến trang ZalopayGateway dựa trên order_url nhận được từ phản hồi khi tạo đơn hàng thành công.
5. User hoàn tất thanh toán trên ZalopayGateway.
6. ZalopayGateway chuyển hướng trở lại MerchantSite.
7. MerchantServer nhận kết quả thanh toán.
8. Merchant Site hiển thị thông báo kết quả thanh toán cho User.

Tích hợp

Phần này tập trung vào cách tích hợp Cổng thanh toán Zalopay. Quy trình bao gồm các bước sau:

1. Hiển thị các hình thức thanh toán trên trang của bạn
2. Sử dụng API Create Order để tạo đơn hàng
3. Điều hướng người dùng đến Cổng thanh toán Zalopay
4. Xử lý hiển thị kết quả giao dịch bằng callback hoặc API Query Order

Bước 1. Hiển thị các hình thức thanh toán

Khi User thực hiện thao tác thanh toán đơn hàng, giao diện MerchantSite cần hiển thị các hình thức thanh toán của Zalopay như: Ví Zalopay, Thẻ Visa/Master/JCB, Thẻ ATM, Apple Pay, Zalopay QR đa năng theo quy cách tham khảo như bên dưới:

Bước 2. Gửi yêu cầu tạo đơn hàng

• Sau khi User bấm Thanh Toán, MerchantSite gửi yêu cầu tạo đơn hàng thanh toán (Tạo đơn hàng) sang cho MerchantServer
  
• Merchant Server sẽ gọi API Create Order đến Zalopay Server.
  
• Đây là một ví dụ về yêu cầu (request) tạo đơn hàng và phản hồi (response) nhận về:

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"
}

Lưu ý: Cách sử dụng tham số bank_code và preferred_payment_menthod trong API Create Order, tương ứng với từng tùy chọn hình thức thanh toán.

bank_code	preferred_payment_method	Nội dung truyền thông tin	Kết quả hiển thị trên trang cổng thanh toán	Ghi chú
Rỗng ("")	[]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": []}"	Danh sách tất cả các hình thức và ngân hàng được hỗ trợ (ATM, CC, Zalopay, Zalopay QR đa năng, Apple Pay ...)	Hình ảnh mô tả 1
Rỗng ("")	["domestic_card", "account"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"domestic_card\", \"account\"]}"	Danh sách tất cả Ngân hàng hỗ trợ, người dùng chọn và nhập thông tin thẻ ATM hoặc tài khoản Ngân hàng tương ứng	Hình ảnh mô tả 2
Rỗng ("")	["Zalopay_wallet"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"Zalopay_wallet\"]}"	Hiển thị Zalopay QR code để thanh toán bằng Zalo/Zalopay	Hình ảnh mô tả 3
Rỗng ("")	["vietqr"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"vietqr\"]}"	Hiển thị Zalopay QR đa năng để thanh toán bằng các ứng dụng Ngân hàng và Zalo/Zalopay	Hình ảnh mô tả 4
Rỗng ("")	["international_card"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"international_card\"]}"	Form hiển thị cho việc nhập thông tin thẻ tín dụng	Hình ảnh mô tả 5
Rỗng ("")	["applepay"]	"bank_code": "", "embed_data": "{\"preferred_payment_method\": [\"applepay\"]}"	Form hiển thị cho việc chọn phương thức Apple Pay	Hình ảnh mô tả 6
BankCode ATM (VTB, VCB,...)	[]	"bank_code": "specific bank code", "embed_data": "{\"preferred_payment_method\": []}"	Form nhập thông tin thẻ của ngân hàng tương ứng Merchant sử dụng API Getlistmerchantbanks để lấy giá trị specific bankcode. (**) Sử dụng API lấy danh sách các ngân hàng được hỗ trợ tại đây	Hình ảnh mô tả 7

#Hình ảnh mô tả 1

#Hình ảnh mô tả 2

#Hình ảnh mô tả 3

#Hình ảnh mô tả 4

#Hình ảnh mô tả 5

#Hình ảnh mô tả 6

#Hình ảnh mô tả 7

Bước 3. Xử lý hiển thị kết quả giao dịch

Khi người mua hoàn tất thanh toán, Cổng thanh toán Zalopay sẽ chuyển hướng trở lại ứng dụng web/app của merchant theo thông tin redirecturl lúc đăng ký ứng dụng hoặc giá trị redirecturl ở bước tạo đơn hàng. Và bước tiếp theo là kiểm tra trạng thái đơn hàng thông qua callback hoặc API Query Order.

Xử lý callback từ ZalopayServer

Sau khi User hoàn thành các bước thanh toán trên ZalopayGateway, nếu trừ tiền user thành công ZalopayServer sẽ trả về (callback/notify) thông tin trạng thái thanh toán cho MerchantServer theo callback_url lúc đăng ký ứng dụng hoặc giá trị callback_url ở bước tạo đơn hàng

Truy vấn trạng thái đơn hàng

Khi người dùng thanh toán thành công, ZalopayServer sẽ gọi callback đến MerchantServer. Tuy nhiên callback có thể bị miss do vấn đề Network/Service Unavailable/..., để trải nghiệm người dùng tốt nhất Merchant cần chủ động truy vấn trạng thái đơn hàng với tần suất 1 phút/lần cho đến khi nhận được callback hoặc hết thời hạn thanh toán đơn hàng.

Điều hướng (redirect) về hệ thống Merchant

Sau khi người dùng hoàn thành thanh toán, ZalopayGateway sẽ redirect về trang hiển thị kết quả của Merchant (theo redirecturl mà Merchant đã cung cấp cho Zalopay).

Dữ liệu truyền vào query string khi Zalopay redirect về trang của Merchant

Tham số	Mô tả
appid	Thông tin app_id của đơn hàng
apptransid	Thông tin app_trans_id của đơn hàng
pmcid	Thông tin kênh thanh toán
bankcode	Thông tin bank_code
amount	Giá trị đơn hàng
discountamount	Giá trị giảm giá
status	Mã trạng thái
checksum	Dùng để kiểm tra redirect có hợp lệ hay không. Kiểm tra hmac hợp lệ: HMAC(hmac_algorithm, key2, appid + "\|"+ apptransid +"\|"+ pmcid +"\|"+ bankcode +"\|"+ amount +"\|"+ discountamount +"\|"+ status)

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

Chú ý: Khi nhận được redirect hợp lệ, Merchant cần kiểm tra xem đã nhận được callback hay chưa, nếu chưa Merchant sử dụng API truy vấn trạng thái thanh toán của đơn hàng để lấy kết quả cuối cùng