POSTGET/api/v2/deposit/*

Nạp tiền tự động & Kiểm tra trạng thái hóa đơn

API tự động tạo lệnh nạp tiền, sinh mã VietQR chuẩn EMVCo và chuỗi ảnh Base64 tiện lợi để render trực tiếp trên UI của quý khách mà không phụ thuộc vào link ảnh ngoài, kèm API kiểm tra đối soát trạng thái thanh toán thời gian thực.

1. Tạo yêu cầu Nạp tiền (Create Deposit)

Endpoint Tạo hóa đơn

POSThttps://api.tracuubank.net/api/v2/deposit/create

Header (Bắt buộc)

Header	Required	Data type	Description
x-api-key	Bắt buộc	string	Mã API Key do hệ thống cấp
x-api-secret	Bắt buộc	string	Mã Secret API do hệ thống cấp
Content-Type	Bắt buộc	string	application/json

Body (JSON)

Payload	Required	Data type	Description
amount	Bắt buộc	number	Số tiền cần nạp (Tối thiểu 10,000 VND)
payment_method	Bắt buộc	string	Mã ngân hàng nhận thanh toán mong muốn (VD: `MB`, `VCB`, `ACB`, `TCB`...) hoặc `VIETQR` để hệ thống tự động chọn cổng thanh toán tối ưu.

Mẫu Code Request Tạo hóa đơn

bash

curl -X POST "https://api.tracuubank.net/api/v2/deposit/create" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "payment_method": "MB"
  }'

Kết quả trả về Tạo hóa đơn (Chuẩn Base64 QR)

json

{
    "code": 200,
    "success": true,
    "msg": "Success",
    "data": {
        "order_id": "DEP_98721345",
        "amount": 100000,
        "received_amount": 100000,
        "transfer_memo": "recharge1",
        "qr_code": "00020101021238540010A00000072701240006970422011063200799990208QRIBFTTA530370454061000005802VN62130809RECHARGE163042A30",
        "qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAYAAACAvzbMAAAAAklEQVR4AewaftIAAAz+SURBVO3BUW4dBxIEwawG73/lWn4vLKDVHnueqYxIvyFJ0m8aJEk6GCRJOhgkSToYJEk6GCRJOhgkSToYJEk6GCRJOhgkSToYJEk6+OI...",
        "bank_info": {
            "bank_code": "MBBank",
            "bank_name": "Ngân hàng TMCP Quân đội",
            "account_number": "6320079999",
            "account_name": "NGUYEN DUY KHANH",
            "bin": "970422"
        },
        "status": "PENDING",
        "expires_at": "2026-10-08T16:07:07.570Z",
        "expires_in": 900
    },
    "timestamp": 1791298500000
}

2. Kiểm tra trạng thái hóa đơn (Check Deposit Status)

Endpoint Kiểm tra hóa đơn

Hỗ trợ cả phương thức POST (truyền order_id qua Body) và GET (truyền order_id qua URL parameter / query).

POSTGET

https://api.tracuubank.net/api/v2/deposit/status

Mẫu Request Kiểm tra

bash

curl -X POST "https://api.tracuubank.net/api/v2/deposit/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "DEP_98721345"
  }'

Kết quả trả về Kiểm tra hóa đơn

json

{
    "code": 200,
    "success": true,
    "msg": "Thanh toán thành công",
    "data": {
        "order_id": "DEP_98721345",
        "trans_id": "GD727568",
        "status": "PAID",
        "is_paid": true,
        "amount": 100000,
        "received_amount": 100000,
        "transfer_memo": "recharge1",
        "bank": "MBBank",
        "bank_name": "Ngân hàng TMCP Quân đội",
        "created_at": "2026-10-08T15:52:07.570Z",
        "updated_at": "2026-10-08T15:54:12.120Z",
        "expires_at": "2026-10-08T16:07:07.570Z",
        "expires_in": 0,
        "paid_at": "2026-10-08T15:54:12.120Z"
    },
    "timestamp": 1791474727597
}

Ý nghĩa các trạng thái (status)

status	is_paid	Ý nghĩa & Hành động đề xuất
PAID	`true`	Đã nhận được tiền chuyển khoản, tài khoản đã được cộng số dư thành công.
PENDING	`false`	Hóa đơn đang chờ người dùng quét mã VietQR và chuyển khoản.
EXPIRED	`false`	Hóa đơn đã quá hạn thời gian thanh toán (15 phút). Cần tạo hóa đơn mới.
CANCELLED	`false`	Hóa đơn đã bị hủy bỏ bởi người dùng hoặc quản trị viên.

3. Phương thức nạp tiền & Ngân hàng nhận (Deposit Method)

Endpoint Lấy phương thức nạp & ngân hàng nhận

Trả về danh sách phương thức thanh toán khả dụng và các ngân hàng nhận được hỗ trợ. Giá trị payment_method trong danh sách này có thể truyền trực tiếp vào API tạo hóa đơn.

GEThttps://api.tracuubank.net/api/v2/deposit/method

bash

curl -X GET "https://api.tracuubank.net/api/v2/deposit/method" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

json

{
    "code": 200,
    "success": true,
    "msg": "Success",
    "data": [
        {
            "id": "6ac0d109793d83d1594cb6c7",
            "payment_method": "MB",
            "bank_code": "MBBank",
            "bank_name": "Ngân hàng TMCP Quân đội",
            "account_name": "NGUYEN DUY KHANH",
            "account_number": "6320079999",
            "bin": "970422",
            "logo": "https://cdn.dichvuright.com/bucket-dichvuright/ibankings/970422.png",
            "min_payment": 10000,
            "max_payment": 50000000,
            "qr_supported": true
        }
    ],
    "timestamp": 1791474727597
}