API tạo QR PayBack tích hợp lên Web/App/CRM/POS

1. 🎯 Mục tiêu

API cho phép đối tác:

• Tạo QR thanh toán tự động với dữ liệu đơn hàng.
• Chuẩn hoá link QR theo hệ thống QR PayBack

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

2. 🔗 Endpoint

POST /qrpayback/create

3. 🔐 Xác thực

Sử dụng API Key trong header:

Authorization: Bearer {api_key}

🔹 Mỗi api_key tương ứng với 1 cửa hàng (shop)
🔹 Không cần truyền shopId trong request

4. 📥 Request

🔹 Cấu trúc chung

{
  "type": "3",
  "amount": 265000,
  "content": "ORD_10005",
  "order": "thông tin đơn hàng"
}

🔹 Ý nghĩa tham số

Field	Bắt buộc	Mô tả
type	✔	Loại tích hợp (1, 2, 3, 4)
amount	✔	Số tiền thanh toán
content		Nội dung chuyển khoản
order		Thông tin đơn hàng (tuỳ theo type)

🔹 Mapping với sh_data

API Field	sh_data
type	t
amount	amount
content	c
order	o

5. 📦 Ví dụ theo từng phương án

🔹 PA4 – Chỉ thanh toán

{
  "type": "4",
  "amount": 100000,
  "content": "PAY_10001"
}

🔹 PA3 – Theo mã đơn hàng

{
  "type": "3",
  "amount": 265000,
  "content": "ORD_10005",
  "order": "ORD_10005"
}

🔹 PA2 – Theo sản phẩm

{
  "type": "2",
  "amount": 265000,
  "content": "ORD_10005",
  "order": [
    "ORD_10005",
    265000,
    [
      ["P001", 55000, 1],
      ["P002", 27000, 2]
    ]
  ]
}

🔹 PA1 – Full dữ liệu

{
  "type": "1",
  "amount": 265000,
  "content": "ORD_10005",
  "order": [
    "ORD_10005",
    265000,
    [
      ["Kem duong A", 55000, 1, 10],
      ["Sua rua mat B", 27000, 2, 8]
    ]
  ]
}

6. 📤 Response

{
  "success": true,
  "data": {
    "qrUrl": "https://zalo.me/s/4236095648487952119/?csid=xxx&sh_type=qr_pay_back&sh_data=xxx",
    "qrImage": "https://abphotos.link/photos/qrcode_base64/{base64_image_string}",
    "shortLink": "https://zalo.me/s/{shortcode}"
  }
}

🔹 Ý nghĩa

Field	Mô tả
qrUrl	Link QR đầy đủ
qrImage	Link ảnh QR
shortLink	Link rút gọn

7. ⚙️ Xử lý nội bộ

Hệ thống QR PayBack sẽ tự động:

• Chuyển dữ liệu request → sh_data
• Encode Base64
• Tạo link QR
• Generate ảnh QR
• Sinh short link

8. ⚠️ Quy định sử dụng

❗ 1. amount

• Bắt buộc
• Phải khớp với đơn hàng thực tế

❗ 2. content

• Nên unique
• Dùng để đối soát giao dịch

❗ 3. order

Type	Yêu cầu
1	Bắt buộc
2	Bắt buộc
3	Bắt buộc
4	Không cần

9. ❌ Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: amount"
  }
}

🔹 Một số lỗi thường gặp

Code	Mô tả
INVALID_REQUEST	Thiếu dữ liệu
INVALID_TYPE	type không hợp lệ
UNAUTHORIZED	Sai API key
INVALID_AMOUNT	amount không hợp lệ

10. 🚀 Quy trình tích hợp

Đối tác thực hiện:

1. Gọi API tạo QR
2. Nhận:
   • qrUrl hoặc
   • qrImage
3. Hiển thị cho khách hàng quét
4. Nhận webhook thanh toán

11. 📞 Hỗ trợ

QR PayBack cung cấp:

• API Key
• Môi trường test
• Hỗ trợ kỹ thuật

12. ✅ Kết luận

API giúp đối tác:

• Tạo QR nhanh chóng
• Chuẩn hoá
• Dễ tích hợp

👉 Đối tác chỉ cần:

• Gọi API
• Hiển thị QR
• Nhận kết quả thanh toán

🚀 QR PayBack sẽ xử lý toàn bộ phần còn lại:

• Encode dữ liệu
• Tạo QR
• Xử lý thanh toán
• Trải nghiệm người dùng