Tài liệu tích hợp QR PayBack lên Web/App/CRM

I. Cấu trúc và cách tạo QR PayBack

1. 🎯 Mục tiêu

Cho phép đối tác:

• Tạo QR PayBack thanh toán cho đơn hàng tích hợp lên Website, App, CRM, POS
• Khi khách hàng quét QR:
  • Mở Zalo Mini App QR PayBack
  • Hiển thị thông tin đơn hàng
  • Thực hiện thanh toán
• Đối soát giao dịch theo mã đơn hàng
• Xuất hóa đơn điện tử

Tài liệu này hướng dẫn cấu trúc và cách tạo 1 mã QR PayBack chủ động theo cấu trúc đó.
Trường hợp khác, bạn có thể tạo QR PayBack với dữ liệu bằng cách gọi API theo tài liệu sau: API tạo QR PayBack tích hợp lên Web/App/CRM/POS

2. 🔗 Cấu trúc link thanh toán

🔹 Format

https://zalo.me/s/{mini_app_id}/?csid={shop_id}&sh_type=qr_pay_back&sh_data={base64}

🔹 Tham số

Params	Mô tả
mini_app_id	ID Mini App QR PayBack
csid	ID cửa hàng (do QR PayBack cung cấp)
sh_type	qr_pay_back (cố định), mở vào thanh toán
sh_data	Dữ liệu thanh toán & đơn hàng (Base64 JSON)

🔹 Ví dụ

https://zalo.me/s/4236095648487952119/?csid=hXLKscHOz&sh_type=qr_pay_back&sh_data=eyJhbW91bnQiOjI3NTAwMCwiYyI6Ik8xMDAwMSIsIm8iOiJPUkRfMTAwMDEifQ

3. 📦 Cấu trúc sh_data

🔹 JSON trước khi encode

{
  "t": "3",
  "amount": 275000,
  "c": "O10001",
  "o": "Đơn hàng"
}

🔹 Ý nghĩa

Field	Bắt buộc	Mô tả
t	✔	Loại tích hợp (1/2/3/4)
amount	✔	Số tiền thanh toán
c		Nội dung chuyển khoản (tùy chọn)
o		Thông tin đơn hàng

🔹 Encode

• JSON → String → Base64
• Gán vào sh_data

4. 🔄 Luồng hoạt động

Tạo QR → Khách quét QR
   ↓
Mở Zalo Mini App
   ↓
QR PayBack đọc tham số từ URL
   ↓
Xử lý theo loại tích hợp (t)
   ↓
Hiển thị thông tin thanh toán
   ↓
Khách nhập thông tin xuất hóa đơn
   ↓
Khách thực hiện thanh toán
   ↓
QR PayBack xác nhận giao dịch
   ↓
Gửi kết quả về đối tác (Webhook/API)

5. 📘 Các phương án tích hợp

5.1. PHƯƠNG ÁN 1 – Full Data in QR

📦 Cấu trúc

{
  "t": "1",
  "amount": 265000,
  "c": "O10005",
  "o": [
    "ORD_10005",
    265000,
    [
      ["Kem duong A", 55000, 1, 10],
      ["Sua rua mat B", 27000, 2, 8]
    ]
  ]
}

✅ Ưu điểm

• Không cần API
• Không cần đồng bộ sản phẩm
• Triển khai nhanh (plug & play)
• Xuất được VAT ngay

❌ Nhược điểm

• QR dài
• Nếu > 500 ký tự hoặc > 5 sản phẩm → Cần gọi API tạo Shortlink trên Zalo

🎯 Phù hợp

• POS/Web đơn giản
• Bán hàng offline / sự kiện
• Đối tác không có hệ thống IT

5.2. PHƯƠNG ÁN 2 – Partial Data

📦 Cấu trúc

{
  "t": "2",
  "amount": 265000,
  "c": "O10005",
  "o": [
    "ORD_10005",
    265000,
    [
      ["P001", 55000, 1],
      ["P002", 27000, 2]
    ]
  ]
}

⚙️ Yêu cầu

• Upload danh mục sản phẩm:
  • product_id
  • name
  • vat_rate

✅ Ưu điểm

• QR ngắn hơn PA1
• Không cần API runtime
• Có kiểm soát dữ liệu

❌ Nhược điểm

• Cần đồng bộ sản phẩm

🎯 Phù hợp

• Cửa hàng vừa & nhỏ
• Hệ thống có danh mục ổn định

5.3. PHƯƠNG ÁN 3 – Order-based

📦 Cấu trúc

{
  "t": "3",
  "amount": 265000,
  "c": "O10005",
  "o": [
    "ORD_10005"
  ]
}

⚙️ Yêu cầu

• API lấy thông tin đơn hàng
• API Webhook nhận thanh toán

✅ Ưu điểm

• QR ngắn nhất
• Dữ liệu chính xác 100%
• Đồng bộ realtime
• Tích hợp sâu (POS, CRM, hóa đơn)

❌ Nhược điểm

• Cần backend/API
• Setup ban đầu cao

5.4. PHƯƠNG ÁN 4 – Payment-only

📦 Cấu trúc

{
  "t": "4",
  "amount": 265000,
  "c": "PAY_10005"
}

⚙️ Đặc điểm

• Không truyền thông tin đơn hàng
• Chỉ dùng:
  • amount
  • c (tùy chọn)
• Không có orderId

✅ Ưu điểm

• Triển khai cực nhanh
• Không cần API
• Không cần đồng bộ sản phẩm
• Không cần quản lý đơn

🎯 Phù hợp

• Thanh toán nhanh
• Thu tiền dịch vụ
• Đã có POS/CRM riêng

🔥 Tổng thể 4 phương án

PA1 → Data trong QR  
PA2 → Product mapping  
PA3 → Order + API  
PA4 → Chỉ thanh toán  

6. 🔌 API tích hợp

6.1. API lấy thông tin đơn hàng (PA3)

Endpoint

POST /order/info

Request

{
  "orderId": "ORD_10005"
}

Response

{
  "success": true,
  "data": {
    "orderId": "ORD_10005",
    "amount": 265000,
    "status": "pending",
    "items": [
      {
        "productId": "P001",
        "name": "Kem dưỡng A",
        "price": 55000,
        "quantity": 1,
        "vatRate": 10
      }
    ]
  }
}

Nếu không tích hợp API, nhân viên sẽ tạo đơn và chọn dữ liệu sản phẩm có sẵn để xuất hóa đơn.

6.2. Webhook thanh toán

Endpoint

POST /webhook_link

Payload

{
  "orderId": "ORD_10005",
  "amount": 265000,
  "transactionId": "TX123456",
  "status": "success"
}

7. 🧾 Xuất hóa đơn

🔹 Nguyên tắc

• Giá sản phẩm đã bao gồm VAT
• Hóa đơn được tạo tại hệ thống đối tác

🔹 Công thức tách VAT

net = price / (1 + vatRate)
vat = price - net

8. 📞 Hỗ trợ tích hợp

QR PayBack cung cấp:

• Shop ID (csid)
• Môi trường test
• Tài liệu API

Đối tác cần:

• Tạo đơn hàng
• Sinh QR theo format
• (Nếu dùng PA3) cung cấp API

👉 QR PayBack sẽ xử lý:

• UI thanh toán
• Trải nghiệm người dùng
• Gửi kết quả giao dịch
• Xuất hóa đơn