Tích hợp Haravan (Thanh toán VietQR)

Haravan là nền tảng quản trị bán hàng đa kênh hàng đầu tại Việt Nam. Dòng Tiền Pro hỗ trợ kết nối 2 chiều với cửa hàng Haravan để tự động tạo mã VietQR theo đơn và kích hoạt hoàn tất đơn hàng qua REST API giao dịch.

Cơ chế tích hợp

1. Khách đặt hàng trên Website Haravan: Chọn phương thức thanh toán chuyển khoản VietQR.
2. Webhook thông báo: Haravan gửi sự kiện orders/create tới endpoint webhook của Dòng Tiền Pro kèm chữ ký X-Haravan-Hmacsha256.
3. Re-fetch đơn hàng: Dòng Tiền Pro tải lại thông tin đơn hàng từ GET /com/orders/{id}.json qua access token của shop.
4. Cập nhật ghi chú: Dòng Tiền Pro tự động thêm mã DTP... và link VietQR vào note_attributes của đơn hàng.
5. Gạch nợ đơn hàng: Khi tiền vào tài khoản ngân hàng và giao dịch được xác thực (verified), Dòng Tiền Pro gọi POST /com/orders/{id}/transactions.json để tạo giao dịch thanh toán thành công, chuyển đơn hàng sang trạng thái Đã thanh toán.

Các bước thiết lập

1. Tạo Phương thức thanh toán thủ công trong Haravan:

   • Đăng nhập vào Haravan Admin (https://{ten-shop}.myharavan.com/admin).
   • Vào Cấu hình (Settings) > Thanh toán (Payments).
   • Trong phần Phương thức thanh toán thủ công, bấm Thêm phương thức tuỳ chỉnh.
   • Tên phương thức: Chuyển khoản qua ngân hàng (VietQR - Dòng Tiền Pro).
   • Hướng dẫn thanh toán: Quét mã VietQR bằng ứng dụng ngân hàng bất kỳ để đơn hàng tự động xác nhận trong 5-10 giây.
   • Bấm Kích hoạt.

2. Cài đặt Ứng dụng Dòng Tiền Pro:

   • Trong trang Quản trị Dòng Tiền Pro, vào Tích hợp > Thêm tích hợp > chọn Haravan.
   • Nhập tên miền cửa hàng Haravan của bạn (ví dụ: cuahang.myharavan.com).
   • Bấm Kết nối, hệ thống sẽ chuyển sang Haravan để bạn đăng nhập và bấm Cho phép cấp quyền cho ứng dụng.

3. Chọn tài khoản nhận tiền:

   • Sau khi liên kết thành công, chọn tài khoản ngân hàng nhận tiền mặc định cho các đơn hàng từ Haravan.
   • Bấm Lưu cấu hình.

4. Kiểm tra thử nghiệm:

   • Đặt một đơn hàng thử nghiệm trên website Haravan của bạn.
   • Kiểm tra thông tin mã chuyển khoản trong chi tiết đơn hàng trên Haravan Admin.
   • Thực hiện chuyển khoản số tiền tương ứng và xem đơn hàng tự động đổi sang trạng thái Đã thanh toán.

Bảo vệ gạch nợ và Xử lý ngoại lệ

Trường hợp	Xử lý của Dòng Tiền Pro	Trạng thái trên Haravan
Khách chuyển đủ tiền	Gọi transactions.json loại Sale, trạng thái success	Đã thanh toán (paid)
Khách chuyển thiếu tiền	Ghi nhận số tiền thiếu, thêm ghi chú vào đơn	Chờ thanh toán (pending)
Khách chuyển thừa tiền	Ghi chú số tiền thừa, hoàn tất thanh toán	Đã thanh toán (paid)
Giao dịch tạm tính (provisional)	Chưa gạch nợ, chờ xác thực ngân hàng	Chờ thanh toán (pending)
Đơn hàng đã huỷ	Bỏ qua gạch nợ, ghi log đối soát	Đã huỷ (cancelled)

Giới hạn tốc độ Leaky Bucket

API Haravan áp dụng cơ chế giới hạn tốc độ Leaky Bucket với dung lượng 80 yêu cầu và tốc độ xả 4 yêu cầu/giây. Dòng Tiền Pro tích hợp bộ điều tiết tốc độ tự động, đảm bảo không bao giờ bị gián đoạn do lỗi HTTP 429 khi có lượng đơn hàng tăng đột biến.