Bắt đầu với TinoPay

TinoPay là dịch vụ nhận thanh toán chuyển khoản của Tino: khách của bạn chuyển khoản vào tài khoản ngân hàng đã liên kết, hoặc vào một tài khoản ảo (VA) riêng; TinoPay ghi nhận giao dịch, gửi webhook tới hệ thống của bạn và thông báo vào Telegram, Zalo, Lark. Tài khoản ngân hàng, tài khoản ảo, giao dịch, webhook và thông báo nằm ở hệ thống TinoPay (https://pay.tino.vn); API merchant của dịch vụ trên api.tino.vn chuyển tiếp tới đó. TinoPay còn có API công khai gọi bằng API token và tích hợp không cần code (Google Sheets, WordPress / WooCommerce, HostBill, Sapo).

Cập nhật: 2026-10-25. Nguồn: module TinoPay của Tino và tài liệu TinoPay API v1.

Thiết lập

1. Đặt mua dịch vụ TinoPay ở tino.vn: mỗi dịch vụ là một merchant.
2. Liên kết tài khoản ngân hàng. Với BIDV doanh nghiệp, gửi yêu cầu liên kết; nhân viên mở dịch vụ với BIDV, xong thì tài khoản hiện ở danh sách tài khoản ngân hàng.
3. Tạo tài khoản ảo khi cần tách tiền theo đơn hàng, cửa hàng hay khách: số VA là mã đầu VA của tài khoản ngân hàng (first_va_number) cộng phần đuôi bạn chọn.
4. Khai mã thanh toán (pay_codes) nếu muốn TinoPay trích mã đơn hàng từ nội dung chuyển khoản.
5. Tạo webhook để nhận từng giao dịch: xem Nhận webhook TinoPay.
6. Muốn báo từng giao dịch vào nhóm chat: xem Thông báo Telegram, Zalo, Lark. Muốn tự đọc giao dịch bằng API công khai của TinoPay: tạo API token.

Gọi API merchant

• PATCH bắt buộc body JSON: API không đọc body dạng form (application/x-www-form-urlencoded) của PATCH. Với PATCH, chỉ gửi trường cần đổi.
• Chỉ các tham số ghi ở từng route được chuyển tiếp; tham số khác bị bỏ qua.
• ID trong đường dẫn sau ID dịch vụ (tài khoản ngân hàng, tài khoản ảo, webhook, log, giao dịch, ứng dụng thông báo, API token) chỉ gồm chữ, số, -, tối đa 64 ký tự; sai dạng trả 404 RESOURCE_NOT_FOUND.
• Timeout: Tino chờ TinoPay tối đa 30 giây mỗi lần và tự thử lại tới 3 lần (cách 1 giây, 2 giây) khi lỗi mạng hoặc lỗi 5xx ở các lệnh thử lại an toàn, nên khi TinoPay chậm một request có thể mất khoảng 95 giây. Đặt timeout ít nhất 100 giây (hoặc báo đang xử lý và cho huỷ). Proxy phía trước có thể cắt sớm hơn và trả 504 với body HTML, không phải JSON: xử lý như lỗi kết nối 502. Tìm nơi nhận của bot Zalo luôn mất khoảng 20 giây.

Từ 27/10/2026 các route TinoPay cũng gọi được qua gateway /v1: https://api.tino.vn/v1/service/<id dịch vụ>/tinopay/… với token ứng dụng OAuth (tinoat_, quyền tinopay:read, tinopay:write) hoặc token API cá nhân (tinopat_), cùng body và câu trả lời. Tạo, xoá API token TinoPay và liên kết tài khoản ngân hàng nhận tiền cần tinopay:owner: chỉ token cá nhân có giới hạn IP, ứng dụng OAuth không bao giờ có. Plugin hay phần mềm của bên thứ ba (ví dụ plugin WooCommerce) nên xin quyền qua Đăng nhập bằng Tino, không hỏi token đăng nhập của khách.

Token đăng nhập (token khách dùng ở khu vực khách hàng tino.vn) vẫn gọi thẳng https://api.tino.vn/service/<id dịch vụ>/tinopay/…; SDK lấy được bằng đăng nhập mã OTP:

from tino_userapi import TinoClient

client = TinoClient()
client.request_login_otp("you@example.com")
client.verify_login_otp("you@example.com", input("Mã OTP: "))
print(client.request("GET", "/service/100001/tinopay/transactions", query={"type": "in"}))

100001 là ID dịch vụ TinoPay: cách tìm ở mục dưới.

Tìm dịch vụ TinoPay

Mỗi tài khoản Tino có tối đa một dịch vụ TinoPay, ứng với một merchant.

1. Nhận diện bằng loại sản phẩm, không theo nhóm hay tên (TinoPay nằm trong nhóm "Dịch vụ khác" dùng chung với dịch vụ khác):

1. Khi mở phần quản lý, gọi Thông tin merchant (GET /service/<id>/tinopay):

Trạng thái merchant

Khi data.status là suspended (hoặc data.suspended_at khác null): báo khách dịch vụ đang tạm ngưng (thanh toán hoá đơn để mở lại) và khoá mọi thao tác ghi. Trong lúc tạm ngưng, giao dịch từ ngân hàng vẫn được ghi nhận nhưng không gửi webhook; mở lại thì tài khoản ngân hàng về trạng thái cũ, đối chiếu giao dịch bỏ lỡ bằng lịch sử giao dịch với webhook_status=none.

Câu trả lời

Thành công: {"data": …}; danh sách phân trang có thêm meta. HTTP 200, 201 khi tạo mới, 202 khi đã xếp hàng gửi lại webhook.

{ "data": [], "meta": { "page": 1, "per_page": 20, "total": 135, "last_page": 7 } }

Danh sách phân trang nhận page và per_page (tối đa 100).

API token

API token dùng để gọi API công khai của TinoPay, ví dụ GET https://pay.tino.vn/api/transactions (header Authorization: Bearer <token>), cùng dữ liệu với trang API Access trên web TinoPay.

• Tạo API token ({name}) trả token 64 ký tự chỉ một lần, trong câu trả lời 201: đưa cho khách sao chép, không lưu, không ghi log. TinoPay chỉ lưu bản băm nên danh sách không có token.
• Không tự thử lại khi lỗi mạng (mỗi lần gọi tạo một token): đọc lại danh sách, thấy token thừa thì thu hồi. Thu hồi có hiệu lực ngay.

Lỗi

{ "error": ["VA_NUMBER_EXISTS"], "message": "Số VA đã tồn tại.", "details": { "account_number": "9624QA01" }, "request_id": "…" }

Rẽ nhánh theo error[0], không theo message (câu tiếng Việt, có thể đổi); message chỉ dùng làm câu dự phòng. Với VALIDATION_FAILED, details là lỗi theo từng trường. Lỗi Tino trả trước khi chuyển tiếp (service_not_found, service_not_active, invalid method, RESOURCE_NOT_FOUND vì ID sai dạng hoặc webhook, ứng dụng thông báo không thuộc merchant) chỉ có error. Khi báo lỗi cho Tino, gửi kèm request_id.

Mã không có trong bảng: hiện message (nếu có) hoặc câu chung, kèm request_id.

Lưu ý

• POST không tự chống lặp: gọi lại một POST (ví dụ tạo tài khoản ảo) là một yêu cầu mới. Đọc lại danh sách trước khi thử lại.
• Tên, email, số điện thoại của merchant không tự đồng bộ với hồ sơ Tino của khách: chỉ đổi qua Sửa thông tin merchant.
• token của webhook là bí mật của khách: khi hiện trên giao diện, che đi và chỉ hiện khi khách bấm xem.
• Tìm nơi nhận, gửi tin thử của thông báo và tạo API token không tự thử lại khi lỗi mạng: để người dùng bấm lại.