Nhận thanh toán QR đầu tiên trong 7 dòng code

Vì sao lại nhanh?

API TConnect yêu cầu mã hóa AES-256-CBC mọi request và quản lý JWT token. Thay vì tự xử lý những phần đó, hãy dùng SDK chính chủ — một file duy nhất, gói sẵn mã hóa, đăng nhập, tự refresh token và mọi endpoint. Bạn chỉ cần gọi create_qr(...).

Bước 1 — Chuẩn bị thông tin

TConnect cấp cho bạn bộ thông tin sau (môi trường Staging):

Thông tin	Dùng để
partner_code	Định danh Merchant
username / password	Đăng nhập JWT
client_id / client_secret	Đăng nhập JWT
secret_key	Khóa AES-256 (chuỗi hex) để mã hóa request
service_code / va / bincode	Lấy từ Get Services — dùng khi tạo QR

Bước 2 — Tải SDK (1 file, copy vào dự án)

Python

📥 Tải tconnect.py · Cài phụ thuộc: pip install requests cryptography

Node.js

📥 Tải tconnect.js · Yêu cầu Node 18+ · không cần npm package nào

Java

📥 Tải TConnect.java · Java 11+ · chỉ dùng thư viện chuẩn JDK

PHP

📥 Tải tconnect.php · PHP 7.4+ · dùng openssl + curl có sẵn

Bước 3 — Tạo QR (7 dòng)

Python

from tconnect import TConnect

tc = TConnect(partner_code="81234567", username="[email protected]", password="Password#123",
              client_id="...", client_secret="...", secret_key="<AES_HEX_KEY>",
              service_code="vccb-qr", va="VA100023312", bincode="970454")

qr = tc.create_qr(order_id="ORDER123", amount=150000)   # tự login + mã hóa + gọi API
print(qr["image_png_base64"])                            # dán vào <img src="data:image/png;base64,...">

Node.js

const { TConnect } = require("./tconnect");

const tc = new TConnect({ partnerCode: "81234567", username: "[email protected]", password: "Password#123",
  clientId: "...", clientSecret: "...", secretKey: "<AES_HEX_KEY>",
  serviceCode: "vccb-qr", va: "VA100023312", bincode: "970454" });

const qr = await tc.createQr({ orderId: "ORDER123", amount: 150000 });
console.log(qr.image_png_base64);

Java

TConnect tc = TConnect.builder()
    .partnerCode("81234567").username("[email protected]").password("Password#123")
    .clientId("...").clientSecret("...").secretKey("<AES_HEX_KEY>")
    .serviceCode("vccb-qr").va("VA100023312").bincode("970454").build();

String qr = tc.createQr("ORDER123", 150000);   // trả JSON có image_png_base64 + qr_content
System.out.println(qr);

PHP

require "tconnect.php";

$tc = new TConnect(["partnerCode" => "81234567", "username" => "[email protected]", "password" => "Password#123",
  "clientId" => "...", "clientSecret" => "...", "secretKey" => "<AES_HEX_KEY>",
  "serviceCode" => "vccb-qr", "va" => "VA100023312", "bincode" => "970454"]);

$qr = $tc->createQr("ORDER123", 150000);
echo $qr["image_png_base64"];

cURL (thô)

# API thô yêu cầu tự mã hóa AES payload rồi mới gọi — 3 bước:
# 1) Login lấy access_token   2) Mã hóa body   3) Gọi create-qr
curl -X POST https://sme-open-api-sandbox.tconnect.vn/openapi/v1/transaction/qr/generate \
  -H "partner-code: 81234567" \
  -H "x-service-code: vccb-qr" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"data":"<AES_ENCRYPTED_PAYLOAD>"}'

Dùng cURL bạn phải tự mã hóa AES và quản lý token. Xem Mã hóa AES. SDK ở các tab bên cạnh làm hết việc này giúp bạn.

Bước 4 — Nhận kết quả thanh toán (IPN webhook)

Khi khách thanh toán, TConnect gọi webhook về server bạn với payload đã mã hóa. SDK giải mã trong 1 dòng:

Python

# Trong route webhook của bạn (Flask/FastAPI/Django...)
event = tc.parse_ipn(request.body)          # -> {"order_id": "...", "amount": ..., ...}
# Đối chiếu event["order_id"] + event["amount"] rồi cập nhật đơn, trả HTTP 200

Node.js

// Trong route webhook (Express...)
const event = tc.parseIpn(req.body);        // -> { order_id, amount, ... }
// Đối chiếu order_id + amount, cập nhật đơn, res.sendStatus(200)

Java

String event = tc.parseIpn(requestBody);    // JSON đã giải mã: {"order_id":...,"amount":...}
// Đối chiếu order_id + amount, cập nhật đơn, trả HTTP 200

PHP

$event = $tc->parseIpn(file_get_contents("php://input")); // -> ["order_id"=>..., "amount"=>...]
// Đối chiếu order_id + amount, cập nhật đơn, trả HTTP 200

Luôn đối chiếu số tiền

Trước khi ghi nhận đơn thành công, hãy so amount trong IPN với số tiền đơn hàng gốc. Chi tiết: IPN Callback.

SDK còn làm được gì?

Ngoài create_qr và parse_ipn, SDK bọc toàn bộ endpoint:

Việc	Python / Node / PHP / Java
Danh sách dịch vụ	get_services() / getServices()
Tạo tài khoản định danh (VA)	create_va() / createVa()
Đẩy thanh toán xuống POS (thẻ) / Soundbox	push_to_device() / pushToDevice()
Tạo / hủy link thanh toán Ecom	create_payment_link() · cancel_payment_link() / createPaymentLink() · cancelPaymentLink()
Tra cứu giao dịch QR	get_qr_transactions() / getQrTransactions()
Tra cứu theo Order ID	check_qr_order() / checkQrOrder()
Giao dịch thẻ / tiền mặt	get_card_transactions() · get_cash_transactions()

Bước tiếp theo

• 👉 Tài liệu API đầy đủ — tham chiếu từng endpoint
• 👉 Mã hóa AES — chi tiết nếu bạn muốn tự triển khai
• 👉 IPN Callback — xử lý webhook

ghi chú

SDK ở đây là bản tham chiếu single-file để bạn tích hợp nhanh. Bạn có thể chỉnh sửa tùy dự án. Bản package chính thức (pip / npm / composer) sẽ được phát hành sau.