Trong trang này
Tích hợp Sapo
Tự động xác nhận thanh toán chuyển khoản cho đơn hàng trên website bán hàng Sapo — không cần lập trình. Khách đặt hàng, trang cảm ơn hiện mã VietQR kèm nội dung chuyển khoản; khách chuyển xong, vài giây sau đơn hàng trên Sapo được ghi nhận đã thanh toán.
#Luồng hoạt động
Khách đặt hàng, chọn "Chuyển khoản ngân hàng"
│
▼
Trang cảm ơn hiện mã VietQR (nội dung: DH<số đơn>)
│ khách quét và chuyển khoản
▼
Ngân hàng báo có ──► TinoPay trích số đơn từ nội dung chuyển khoản
│
▼
Sapo Admin API: ghi nhận thanh toán cho đơn ──► Đơn "Đã thanh toán"
- Chuyển đủ tiền (hoặc dư): TinoPay ghi nhận thanh toán bằng đúng tổng tiền của đơn.
- Chuyển thiếu: đơn giữ nguyên, TinoPay ghi lại trong mục Đối soát gần đây để bạn xử lý.
- Đơn đã thanh toán hoặc đã huỷ: bỏ qua, không ghi nhận trùng.
- Trang cảm ơn tự đổi sang "Đã nhận … cho đơn …" khi đơn được ghi nhận.
#Yêu cầu
- Website bán hàng Sapo (địa chỉ quản trị dạng
https://ten-cua-hang.mysapo.net/admin). Chưa hỗ trợ Sapo Omni / POS. - Tài khoản TinoPay và ít nhất một tài khoản ngân hàng đã kết nối. Với BIDV cần chọn tài khoản ảo (VA) nhận tiền.
#Cài đặt
#Bước 1 — Tạo ứng dụng riêng trên Sapo
- Vào Sapo Admin → Ứng dụng → Ứng dụng riêng → Tạo ứng dụng riêng.
- Đặt tên, ví dụ
TinoPay. - Ở phần phân quyền, dòng Đơn hàng, giao dịch và vận chuyển chọn Đọc và ghi. Các quyền khác để Không cho phép.
- Bấm Lưu, sao chép API Key và API Secret.
#Bước 2 — Thêm cửa hàng trên TinoPay
Dashboard TinoPay → Tích hợp → Sapo → Thêm cửa hàng:
| Trường | Mô tả |
|---|---|
| Đặt tên cho tích hợp | Tên tuỳ ý, ví dụ Sapo Web. |
| ① Ngân hàng nhận thanh toán | Tài khoản ngân hàng hiện trên QR. Với BIDV chọn thêm tài khoản ảo — chỉ giao dịch vào VA này mới được đối soát. |
| ① Tiền tố mã thanh toán | Chọn từ các tiền tố đã khai báo ở Cài đặt → Cấu trúc mã thanh toán (ví dụ DH). Nội dung chuyển khoản = tiền tố + số đơn Sapo, ví dụ đơn #1001 → DH1001. |
| ② URL cửa hàng | Dạng https://ten-cua-hang.mysapo.net (dùng địa chỉ .mysapo.net, không dùng tên miền riêng). |
| ② API Key / API Secret | Lấy ở bước 1. Secret được mã hoá khi lưu; khi sửa, để trống để giữ secret cũ. |
| ③ Tùy chỉnh cấu hình tham số | Tham số của giao dịch TinoPay tạo trên đơn Sapo (xem bên dưới). |
| Trạng thái | Kích hoạt / Tạm dừng. |
TinoPay kiểm tra kết nối tới Sapo trước khi lưu. Bấm Kiểm tra kết nối để thử trước.
Tùy chỉnh cấu hình tham số
Khi khách chuyển đủ tiền, TinoPay tạo một giao dịch thanh toán trên đơn qua Sapo Transaction API (POST /admin/orders/{id}/transactions.json) với số tiền bằng tổng đơn. Ba tham số dưới đây quyết định giao dịch đó:
| Tham số | Giá trị | Ý nghĩa |
|---|---|---|
kind |
capture (mặc định) / sale / authorization |
Loại giao dịch. capture = thu tiền cho đơn đã đặt, phù hợp với đơn chuyển khoản thủ công. |
source_name |
[Không tùy chỉnh] / web / pos / iphone / android |
Nguồn giao dịch. Để trống thì Sapo tự đặt. |
status |
[Không tùy chỉnh] / success / pending / failure / error |
Trạng thái giao dịch. Để trống thì Sapo tự đặt. |
Để mặc định (capture, không tùy chỉnh) là phù hợp với đa số cửa hàng; chỉ đổi khi đơn trên Sapo chưa chuyển sang Đã thanh toán sau khi ghi nhận.
#Bước 3 — Thêm phương thức thanh toán
- Sapo Admin → Cấu hình → Phương thức thanh toán → Phương thức thanh toán thủ công → Thêm phương thức.
- Loại phương thức: Chuyển khoản. Tên phương thức cần có chữ Chuyển khoản, ví dụ
Chuyển khoản ngân hàng (Tự động xác nhận)— trang cảm ơn chỉ hiện QR cho đơn chọn phương thức chuyển khoản, không hiện cho COD. - Hướng dẫn thanh toán: ví dụ "Quét mã QR ở trang hoàn tất đơn hàng, giữ nguyên nội dung chuyển khoản. Đơn được xác nhận tự động sau vài giây."
- Bấm Lưu.
#Bước 4 — Dán mã nhúng vào trang thanh toán
- Trên TinoPay, ở thẻ cửa hàng, bấm Copy tại Mã nhúng trang thanh toán. Mã có dạng:
<script src="https://ipn.pay.tino.vn/sapo/<khoá-cửa-hàng>.js" data-order="{{ order.order_number }}" async></script>
- Sapo Admin → Cấu hình → Trang thanh toán → mục Xử lý đơn hàng → dán vào ô Nội dung thông báo thêm (hoặc Nội dung chân trang thanh toán), rồi Lưu.
Mã nhúng chỉ chứa khoá công khai của cửa hàng, không chứa API Key/Secret. Trang cảm ơn chỉ hiện QR cho đơn tạo trong 7 ngày gần nhất.
#Bước 5 — Kiểm tra
Đặt thử một đơn, chọn phương thức chuyển khoản ở bước 3. Trang hoàn tất đơn hàng hiện QR là cấu hình đã đúng. Chuyển khoản thử một khoản nhỏ: đơn trên Sapo chuyển sang Đã thanh toán và dòng đối soát hiện ở trang Tích hợp → Sapo.
#Đối soát
Trang Tích hợp → Sapo hiện 20 giao dịch có mã đơn gần nhất:
| Trạng thái | Ý nghĩa |
|---|---|
| Đã ghi nhận | Đã ghi nhận thanh toán cho đơn trên Sapo. |
| Chuyển thiếu | Số tiền nhỏ hơn tổng đơn, chưa ghi nhận. Xử lý thủ công trên Sapo. |
| Đã thanh toán trước | Đơn đã ở trạng thái đã thanh toán, bỏ qua. |
| Không thấy đơn | Không có đơn với số đơn trong nội dung chuyển khoản. |
| Đơn đã huỷ | Đơn đã huỷ, không ghi nhận. |
| Lỗi | Sapo từ chối hoặc không kết nối được (sai API key/secret, ứng dụng bị xoá…). |
Bấm Gửi lại hook ở trang chi tiết giao dịch để đối soát lại sau khi sửa cấu hình; đơn đã thanh toán sẽ không bị ghi nhận trùng.
#Xử lý sự cố
| Hiện tượng | Nguyên nhân thường gặp |
|---|---|
| Trang cảm ơn không hiện QR | Chưa dán mã nhúng, tích hợp đang tạm dừng, hoặc tên phương thức thanh toán trên Sapo không có chữ "Chuyển khoản". |
| Lưu tích hợp báo sai API key/secret | Ứng dụng riêng chưa có quyền Đọc và ghi đơn hàng, hoặc sao chép thiếu ký tự. |
| Khách đã chuyển nhưng đơn chưa xác nhận | Nội dung chuyển khoản thiếu mã đơn (DH1001), chuyển thiếu tiền, hoặc chuyển vào tài khoản/VA khác với tài khoản đã chọn. Xem mục Đối soát gần đây. |