Skip to main content
Version: 1.1.0 (Latest)

Khởi tạo lệnh chi hộ

POST
URLhttps://open-api.tingee.vn/v1/direct-link/create-transfer

Khởi tạo lệnh chi hộ theo mô hình Maker/Checker (dành riêng cho BIDV)

Header Request​

HeaderBắt buộcMô tả
Content-Type✓application/json
x-client-id✓Mã định danh của đối tác do TINGEE cung cấp.
x-signature✓Chữ ký xác thực HMAC SHA512.
x-request-timestamp✓Thời gian gửi request (format: yyyyMMddHHmmssSSS, múi giờ UTC+7)

Body Parameter​

💡 Cơ chế áp dụng thông số giao dịch (Global vs Record-level)

Hệ thống hỗ trợ truyền tham số theo hai cấp độ để tối ưu hóa việc tạo lệnh chi đơn và chi lô:

  • Cấp độ chung (Global): Các trường như transactionType, feeMethod, paymentMethod, và effectiveDate khi được truyền ở cấu trúc ngoài cùng của payload sẽ đóng vai trò là giá trị mặc định áp dụng cho tất cả các giao dịch bên trong danh sách `records`.
  • Cấp độ chi tiết (Record-level): Nếu các trường trên được chỉ định cụ thể cho từng phần tử trong mảng `records`, hệ thống sẽ ưu tiên sử dụng giá trị này, ghi đè lên giá trị mặc định ở cấp độ chung.
TrườngKiểuBắt buộcMô tả
bankBinstring✓Mã BIN ngân hàng. Truyền cố định 970418 (Mã BIN của BIDV)
actionstring✓Loại thao tác của người tạo lệnh Chi hộ
- REQUEST_APPROVAL: Lưu và Đẩy duyệt giao dịch chi hộ ngay lập tức
- INIT: Lưu nháp giao dịch chi hộ để đẩy duyệt sau
actionTypestring✓Mục đích của lệnh Chi hộ
- INTERNAL_TRANSFER: Chuyển tiền trong nước
- SALARY: Thanh toán Lương
- BILL_PAYMENT: Thanh toán Hóa đơn-Bảng kê
senderAccountNumberstring✓Số tài khoản thanh toán (trích nợ)
senderAccountNamestring✕Tên chủ tài khoản thanh toán.
transactionTypestring~Loại giao dịch (áp dụng chung)
- in-bank : Nội bộ ngân hàng
- fast-out: Chuyển nhanh NAPAS 247
- regular-out: Chuyển thường liên ngân hàng
Bắt buộc nếu không truyền ở cấp chi tiết.
feeMethodstring~Cách thức thu phí (áp dụng chung)
- O : Tài khoản thanh toán chịu phí
- B: Tài khoản nhận tiền chịu phí
Bắt buộc nếu không truyền ở cấp chi tiết.
paymentMethodstring~Cách thức hạch toán (áp dụng chung)
- to-acc : Hạch toán đến STK người nhận
- to-id: Hạch toán đến GTTT người nhận
Bắt buộc nếu không truyền ở cấp chi tiết.
effectiveDatestring~Ngày hạch toán giao dịch phía Ngân hàng (format: yyyy-MM-dd) (áp dụng chung)
Bắt buộc nếu không truyền ở cấp chi tiết.
remarkstring~Nội dung chuyển tiền / diễn giải giao dịch chung
Bắt buộc truyền với giao dịch chi lô. Với chi đơn lẻ không bắt buộc.
approvalNotestring~Ghi chú của người tạo lệnh
Bắt buộc khi truyền thao tác action là: REQUEST_APPROVAL
currencystring✕Loại tiền tệ hạch toán của tài khoản thanh toán (mặc định: VND)
recordsarray✓Danh sách bản ghi giao dịch cần tạo
- Lệnh chi đơn: mảng gồm 1 phần tử
- Lệnh chi lô: mảng gồm n phần tử

Chi tiết phần tử trong records​

TrườngKiểuBắt buộcMô tả
requestIdstring✓Mã tham chiếu giao dịch do đối tác tự sinh, dùng để đối chiếu kết quả. Phải là duy nhất với mỗi giao dịch
receiverAccountNumberstring~Số tài khoản của người nhận tiền
Bắt buộc khi paymentMethod là to-acc
receiverIdstring~Số giấy tờ tùy thân (CMND/CCCD/Hộ chiếu) của người nhận
Bắt buộc khi paymentMethod là to-id
receiverIdIssueDatestring~Ngày cấp GTTT (Định dạng: yyyy-MM-dd)
Bắt buộc khi paymentMethod là to-id
receiverIdIssueAddressstring~Nơi cấp GTTT
Bắt buộc khi paymentMethod là to-id
receiverBranchCodestring~Mã chi nhánh ngân hàng nhận tiền
Bắt buộc khi paymentMethod là to-id
receiverAccountNamestring✓Tên chủ tài khoản người nhận
(không dấu, viết IN HOA)
amountnumber✓Số tiền giao dịch
receiverBankBinstring✓Mã BIN ngân hàng nhận tiền. Xem tại Danh sách ngân hàng hỗ trợ
remarkstring~Nội dung chuyển tiền / diễn giải giao dịch
Bắt buộc khi khởi tạo giao dịch chi theo lô. Với chi đơn lẻ không bắt buộc.
receiverCurrencystring✕Loại tiền tệ của tài khoản người nhận (mặc định: VND)
transactionTypestring~Loại giao dịch (áp dụng riêng)
- in-bank: Nội bộ ngân hàng
- fast-out: Chuyển nhanh NAPAS 247
- regular-out: Chuyển thường liên ngân hàng
Nếu truyền sẽ ưu tiên sử dụng (ghi đè giá trị chung). Bắt buộc nếu chưa cấu hình ở cấp độ chung.
paymentMethodstring~Cách thức hạch toán (áp dụng riêng)
- to-acc: Hạch toán đến STK người nhận
- to-id: Hạch toán đến GTTT người nhận
Nếu truyền sẽ ưu tiên sử dụng (ghi đè giá trị chung). Bắt buộc nếu chưa cấu hình ở cấp độ chung.
effectiveDatestring~Ngày hạch toán giao dịch (áp dụng riêng)
Định dạng: yyyy-MM-dd.
Nếu truyền sẽ ưu tiên sử dụng (ghi đè giá trị chung).
feeMethodstring~Cách thức thu phí (áp dụng riêng)
- O: Tài khoản thanh toán chịu phí
- B: Tài khoản nhận tiền chịu phí
Nếu truyền sẽ ưu tiên sử dụng (ghi đè giá trị chung). Bắt buộc nếu chưa cấu hình ở cấp độ chung.

Payload Request mẫu​

Để tương thích với 4 kịch bản ở phần Response, dưới đây là các cấu trúc Payload tương ứng mà bạn cần gửi lên (sự khác biệt chỉ nằm ở trường action và mảng records). Bạn có thể click chọn từng Tab dưới đây, toàn bộ Ví dụ mã nguồn và Response mẫu bên dưới sẽ tự động đồng bộ theo kịch bản mà bạn chọn!

{
  "actionType": "INTERNAL_TRANSFER",
  "transactionType": "in-bank",
  "action": "INIT",
  "bankBin": "970418",
  "senderAccountNumber": "8600007007",
  "currency": "VND",
  "feeMethod": "O",
  "paymentMethod": "to-acc",
  "effectiveDate": "2026-06-04",
  "records": [
    {
      "requestId": "TRANS_1006_A04",
      "receiverAccountNumber": "2220366666",
      "receiverAccountName": "NGUYEN VAN A",
      "amount": 32987,
      "receiverBankBin": "970418",
      "remark": "Chuyen tien"
    }
  ]
}

Ví dụ mã nguồn​

curl --location --request POST 'https://open-api.tingee.vn/v1/direct-link/create-transfer' \
--header 'accept: application/json' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'x-request-timestamp: 20251110175110111' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{
"actionType": "INTERNAL_TRANSFER",
"action": "INIT",
"bankBin": "970418",
"senderAccountNumber": "8600007007",
"currency": "VND",
"feeMethod": "O",
"paymentMethod": "to-acc",
"effectiveDate": "2026-06-04",
"records": [
  {
    "requestId": "TRANS_1006_A04",
    "receiverAccountNumber": "2220366666",
    "receiverAccountName": "NGUYEN VAN A",
    "amount": 32987,
    "receiverBankBin": "970418",
    "remark": "Chuyen tien"
  }
]
}'

Response mẫu​

Tùy thuộc vào tham số action (Lưu nháp hay Đẩy duyệt) và số lượng giao dịch (Chi đơn lẻ hay Chi lô), API sẽ trả về cấu trúc tương ứng với 1 trong 4 trường hợp dưới đây:

Phản hồi khi gọi lệnh lưu nháp (action="INIT") cho một giao dịch duy nhất.

{
  "code": "00",
  "message": "Success",
  "data": {
    "status": "SUCCESS",
    "totalRecords": 1,
    "validRecords": 1,
    "invalidRecords": 0,
    "requireAuth": false,
    "transAuth": null,
    "records": [
      {
        "requestId": "TRANS_1006_A04",
        "status": "INIT",
        "transactionId": "PM0226061000074420",
        "transactionCode": "PM02",
        "message": null,
        "feeTotal": 11000
      }
    ]
  }
}

Cấu trúc Response data​

TrườngKiểuMô tả
statusstringTrạng thái giao dịch của lệnh chi (VD: SUCCESS cho Lưu nháp, PENDING_CONFIRMATION cho Đẩy duyệt).
batchIdstringMã lô giao dịch (chỉ trả về khi tạo lệnh chi lô).
confirmIdstringChuỗi key xác nhận giao dịch (chỉ trả về khi tạo lệnh đẩy duyệt REQUEST_APPROVAL).
transactionIdstringMã giao dịch cấp Lô (đối với giao dịch Lương/Bảng kê).
transactionCodestringMã loại giao dịch phía ngân hàng (đối với giao dịch lô).
totalRecordsnumberTổng số giao dịch.
validRecordsnumberSố lượng giao dịch hợp lệ.
invalidRecordsnumberSố lượng giao dịch không hợp lệ.
requireAuthbooleanYêu cầu xác thực giao dịch thêm (VD: SmartOTP).
transAuthobjectThông tin cấu hình xác thực (nếu requireAuth = true).
recordsarrayDanh sách kết quả chi tiết từng giao dịch (Với lô đẩy duyệt REQUEST_APPROVAL, mảng này sẽ rỗng do chưa có kết quả xử lý của từng lệnh con).

Chi tiết data.transAuth (Nếu yêu cầu xác thực thêm)​

TrườngKiểuMô tả
authTypestringPhương thức xác thực (VD: SMARTOTP).
expTimenumberThời gian hiệu lực của mã QR (tính bằng giây).
qrDatastringChuỗi dữ liệu dùng để render hình ảnh QR Code. Dùng để quét trên app ngân hàng lấy mã OTP.

Chi tiết phần tử trong data.records​

TrườngKiểuMô tả
requestIdstringMã tham chiếu giao dịch đã gửi lên.
statusstringTrạng thái giao dịch (VD: PENDING_APPROVAL).
transactionIdstringMã giao dịch trên hệ thống ngân hàng (dành cho giao dịch đơn).
transactionSubIdstringMã giao dịch con (dành cho giao dịch lô Lương/Bảng kê).
transactionCodestringMã loại giao dịch phía ngân hàng (dành cho giao dịch đơn).
messagestringThông báo lỗi (nếu có).
feeTotalnumberTổng phí giao dịch.
Hướng dẫn xác thực SmartOTP (Đẩy duyệt BIDV)

Khi đẩy duyệt giao dịch, nếu hệ thống trả về requireAuth: true kèm theo transAuth.qrData, bạn cần thực hiện các bước sau để lấy mã OTP:

  1. Chuyển đổi chuỗi ký tự trong qrData thành một hình ảnh mã QR (QR Code image).
  2. Mở ứng dụng BIDV Direct trên thiết bị (đã được cấp quyền duyệt lệnh).
  3. Sử dụng tính năng quét mã QR trong ứng dụng để quét hình ảnh QR vừa tạo.
  4. Kiểm tra kỹ thông tin giao dịch trên màn hình ứng dụng và xác nhận bằng mã PIN của BIDV Direct.
  5. Sau khi xác nhận mã PIN, một mã SmartOTP sẽ được hiển thị trên màn hình.
  6. Lấy mã SmartOTP này truyền vào tham số otp trong API Xác nhận lệnh chuyển khoản để hoàn tất giao dịch.

Mã lỗi thường gặp​

CodeMô tảHướng xử lý
90Sai format timestampKiểm tra format yyyyMMddHHmmssSSS.
91Request quá hạnKiểm tra thời gian gửi request.
97Sai chữ kýKiểm tra lại Secret Key và logic tạo Signature.
OthersLỗi khácXem Danh sách mã lỗi.

Copyright © 2026 TINGEE - Giải pháp thanh toán bởi HENO.