TConnect Payment Open API
👋 Chào mừng bạn đến với TConnect Payment Open API - giải pháp thanh toán tự động hóa toàn diện cho mọi hệ thống từ ERP, PMS, HIS, ứng dụng AI đến Kiosk và thiết bị POS. Hãy khám phá tài liệu này để tìm mô hình thanh toán phù hợp nhất cho dự án của bạn!
⚡ Bắt đầu nhanh — Nhận thanh toán QR trong 7 dòng code với SDK chính chủ (Python / Node / Java / PHP) đã gói sẵn mã hóa AES và JWT.
Tài liệu tích hợp hệ thống thanh toán OPEN API của TConnect.
API này giúp bạn làm gì?
| Tính năng | Mô tả |
|---|---|
| 🔐 Xác thực JWT | Đăng nhập và quản lý phiên bảo mật với Access Token + Refresh Token |
| 🔳 Tạo mã QR | Khởi tạo QR tĩnh hoặc QR động chứa số tiền đơn hàng |
| 🔔 IPN Callback | Nhận thông báo thanh toán thành công tức thời |
| 📊 Lịch sử giao dịch | Tra cứu giao dịch QR, tiền mặt có phân trang |
| ⚙️ Danh sách dịch vụ | Kiểm tra các cổng thanh toán đang được cấp phép |
Xác thực (Authentication)
Sử dụng JWT Bearer token. Gọi POST /openapi/v1/auth/login để lấy access_token,
sau đó thêm vào header Authorization: Bearer <token> cho mọi request tiếp theo.
HTTP: Bearer Auth
| Thuộc tính | Giá trị |
|---|---|
| Security Scheme Type | http |
| HTTP Authorization Scheme | bearer |
| Bearer format | JWT |
JWT access_token lấy từ API Login.
API Key: partnerCode
| Thuộc tính | Giá trị |
|---|---|
| Security Scheme Type | apiKey |
| Header parameter name | Partner-Code |
Mã định danh Merchant (TCONNECT cung cấp).
Mã hóa (Encryption)
Toàn bộ Request Body (trừ API Get Services) được mã hóa AES-256-CBC.
Trường data chứa payload đã mã hóa dưới dạng Hexadecimal.
Toàn bộ Request Body đều phải được mã hóa AES-256-CBC.
Xem chi tiết tại Mã hóa AES.
Thông tin môi trường
| Môi trường | Base URL |
|---|---|
| Staging | https://sme-open-api-sandbox.tconnect.vn |
| Production | Được cung cấp sau khi hoàn tất kiểm thử |
Thông tin thử nghiệm (Sandbox)
Bộ thông tin Sandbox dưới đây đã sẵn sàng để bạn — hoặc một AI/Agent — chạy trọn luồng Login → Get Services → Create QR → Check Order Status mà không cần đăng ký thêm. Đây cũng chính là thông tin trong file đặc tả tải về (single-file).
| Thông tin | Giá trị |
|---|---|
| Base URL | https://sme-open-api-sandbox.tconnect.vn |
| Partner-Code | KH_0000024 |
| OAuth Username | [email protected] |
| OAuth Password | N343#2^zPDLOx4{v |
| Client ID | sh6dhA4hTu-rE0AFhgtHtg |
| Client Secret Key | GsUppywKmcPyJUk6lwajsQ6CHtxbEXJ8 |
| AES Secret Key (hex, 32 byte) | 5fed5c2bd6d5ea44d33d71b3bdd02193bb28ea3ad026f85a07c82d70536d1f91 |
| Merchant CIF | KH_0000024 — chính là internal_code khi Create VA; với đối tác này CIF = Partner-Code |
| Số tài khoản gốc (origin) | 31052426 — là bank_account_no khi Create VA |
Giá trị lấy được từ sandbox (cần cho Create QR / Check Status):
| Thông tin | Giá trị | Lấy từ đâu |
|---|---|---|
x-service-code | vccb-qr | Từ Get Services (payment_method=qr) — dịch vụ QR BVBank |
bincode | 970454 | Mã BIN của BVBank (VCCB) |
va / acc_no (VA nhận tiền) | 99MPI0000342300013 | VA nhận tiền của Merchant — dùng làm va khi Create QR và acc_no khi Check Order Status |
- Chỉ dùng cho môi trường Sandbox — không dùng cho production.
- AI/Agent, script: WAF chặn client mặc định (
curl,python-urllib…) trả 403. Luôn gửi headerUser-Agentcủa trình duyệt thật, ví dụ:Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36.
1. Luồng thanh toán bằng QR
2. Luồng thanh toán bằng QR trên thiết bị (POS, Soundbox)
Bước tiếp theo
- 👉 API Login — Bắt đầu từ bước xác thực
- 👉 Get Services — Lấy danh sách dịch vụ thanh toán
- 👉 Mã hóa AES — Chi tiết mã hóa request
Liên hệ
TConnect
Email: [email protected]
URL: https://tconnect.vn