API xuất hoá đơn tự động

Tích hợp thanh toán VietQR và phát hành hóa đơn điện tử hoàn toàn tự động

1. Tổng quan

API Server xuất hóa đơn tự động của Tingo Pay cho phép doanh nghiệp kết nối hệ thống bán hàng, website, ứng dụng hoặc phần mềm quản lý với hệ thống thanh toán VietQR và hóa đơn điện tử.

Thông qua một luồng tích hợp duy nhất, hệ thống có thể:

Tạo đơn hàng và mã thanh toán VietQR.
Gửi thông tin người mua và hàng hóa.
Nhận thông báo khi khách hàng thanh toán thành công.
Tự động phát hành hóa đơn điện tử.
Nhận callback khi hóa đơn được phát hành.
Tra cứu trạng thái đơn hàng và hóa đơn.
Tải hóa đơn điện tử dưới dạng PDF.
Kiểm tra trạng thái cấu hình xuất hóa đơn.

Điểm liên kết xuyên suốt giữa đơn hàng – giao dịch thanh toán – hóa đơn là orderId. Đối tác truyền orderId khi tạo đơn hàng; giá trị này tiếp tục được sử dụng trong callback và các API tra cứu.

2. Luồng hoạt động

Quy trình tích hợp được thiết kế theo mô hình:

Xác thực → Tạo đơn hàng → Thanh toán → Callback giao dịch → Xuất hóa đơn → Callback hóa đơn → Tra cứu / Tải PDF

Quy trình chi tiết

Bước 1 – Xác thực

Hệ thống đối tác gọi API Get Token để nhận access_token.

Bước 2 – Tạo đơn hàng

Đối tác gửi thông tin:

Tài khoản ngân hàng nhận tiền.
orderId.
Người mua.
Danh sách hàng hóa.
Đơn giá.
Số lượng.
Thuế suất.

Hệ thống tính tổng tiền đơn hàng và tạo mã VietQR.

Bước 3 – Khách hàng thanh toán

Khách hàng quét mã VietQR và thực hiện thanh toán.

Bước 4 – Callback giao dịch

Sau khi giao dịch thành công, VietQR gửi callback về hệ thống đối tác. Callback chứa orderId để đối tác xác định chính xác đơn hàng đã thanh toán.

Bước 5 – Xuất hóa đơn tự động

Hệ thống đối soát giao dịch theo orderId. Nếu tài khoản ngân hàng đã được cấu hình xuất hóa đơn, hệ thống sẽ phát hành hóa đơn điện tử theo thông tin người mua và hàng hóa của đơn hàng.

Bước 6 – Callback hóa đơn

Khi hóa đơn được phát hành, VietQR gửi callback hóa đơn về hệ thống đối tác, tiếp tục sử dụng orderId để liên kết với đơn hàng.

Bước 7 – Tra cứu và tải hóa đơn

Đối tác có thể:

Tra cứu đơn hàng.
Tra cứu hóa đơn.
Lấy thông tin hóa đơn.
Tải file PDF hóa đơn.

3. Môi trường API

Tất cả API sử dụng HTTPS và dữ liệu trao đổi chủ yếu ở định dạng application/json.

Môi trường	Base URL
Kiểm thử	`https://dev.vietqr.org/vqr`
Vận hành	`https://api.vietqr.org/vqr`

API tải PDF hóa đơn trả về dữ liệu file nhị phân.

4. Xác thực API

API sử dụng cơ chế Bearer Token.

Đối tác → VietQR

Đối tác gọi API:

POST /api/token_generate

với header:

Authorization: Basic Base64(username:password)

Sau khi xác thực thành công, hệ thống trả về:

text

{
  "access_token": "eyJhbGciOiJIUzUxMiJ9....",
  "token_type": "Bearer",
  "expires_in": 300
}

access_token có thời hạn 300 giây. Khi token hết hạn, đối tác thực hiện Get Token lại.

Các API tiếp theo sử dụng:

text

Authorization: Bearer <access_token>

5. Danh sách API

API do VietQR - Tingo pay cung cấp

API	Method	Endpoint	Chức năng
Get Token	POST	`/api/token_generate`	Lấy Bearer Token
Tạo đơn hàng	POST	`/api/qr/generate-customer-order`	Tạo đơn hàng và mã VietQR
Tra cứu đơn hàng	POST	`/api/order/query`	Tra cứu trạng thái đơn hàng
Tra cứu hóa đơn	POST	`/api/invoice/query`	Tra cứu hóa đơn
Tải PDF hóa đơn	GET	`/api/invoice/export-pdf`	Tải hóa đơn PDF
Kiểm tra cấu hình	GET	`/api/invoice-config/status`	Kiểm tra trạng thái cấu hình hóa đơn

API do đối tác triển khai

API	Method	Endpoint	Chức năng
Get Token	POST	`/<basepath>/api/token_generate`	Cấp token cho VietQR
Callback giao dịch	POST	`/<basepath>/bank/api/transaction-sync`	Nhận thông báo thanh toán
Callback hóa đơn	POST	`/<basepath>/api/invoice-sync`	Nhận kết quả phát hành hóa đơn

6. API Tạo đơn hàng

Endpoint

text

POST /vqr/api/qr/generate-customer-order

API cho phép đối tác tạo đơn hàng kèm thông tin người mua, danh sách hàng hóa và mã thanh toán VietQR.

Số tiền thanh toán được hệ thống tự động tính từ danh sách items.

Không gửi trực tiếp trường amount. Hệ thống tính amount bằng tổng unitPriceAfterTax × quantity của toàn bộ sản phẩm.

Thông tin thanh toán chính

Field	Bắt buộc	Mô tả
`bankCode`	Có	Mã ngân hàng
`bankAccount`	Có	Tài khoản nhận tiền
`userBankName`	Có	Tên chủ tài khoản
`content`	Có	Nội dung chuyển tiền
`transType`	Không	`C` hoặc `D`, mặc định `C`
`orderId`	Không	Mã đơn hàng
`qrType`	Không	Loại QR, sử dụng `0`
`buyer`	Không	Thông tin người mua
`items`	Có	Danh sách hàng hóa

7. Thông tin người mua

Đối tượng buyer có thể bao gồm:

text

{
  "name": "Tran Van B",
  "companyName": "ABC Company",
  "taxCode": "9876543210",
  "address": "12 Nguyen Hue, Q1, TP.HCM",
  "phone": "0901234567",
  "email": "[email protected]"
}

Nếu không truyền buyer, hóa đơn được ghi nhận theo người mua vãng lai.

8. Danh sách hàng hóa

Mỗi sản phẩm trong items bao gồm:

Field	Bắt buộc	Mô tả
`code`	Không	Mã hàng hóa
`name`	Có	Tên hàng hóa/dịch vụ
`quantity`	Có	Số lượng, tối thiểu 1
`unit`	Không	Đơn vị tính
`unitPriceAfterTax`	Có	Đơn giá đã gồm thuế
`taxRate`	Có	Thuế suất

Đơn giá unitPriceAfterTax được truyền theo đơn vị VND, là số nguyên và phải lớn hơn 0.

9. Ví dụ Request

text

{
  "content": "TT don pepsi08024",
  "bankAccount": "05643598501",
  "bankCode": "TPB",
  "userBankName": "VU DUY ANH",
  "transType": "C",
  "orderId": "pepsi08024",
  "qrType": 0,

  "buyer": {
    "name": "Tran Van B",
    "taxCode": "9876543210",
    "address": "12 Nguyen Hue, Q1, TP.HCM",
    "phone": "0901234567",
    "email": "[email protected]"
  },

  "items": [
    {
      "code": "SP001",
      "name": "Pepsi lon 330ml",
      "quantity": 5,
      "unit": "Lon",
      "unitPriceAfterTax": 10000,
      "taxRate": "8"
    }
  ]
}

Trong ví dụ trên, tổng tiền thanh toán được hệ thống tính tự động:

5 × 10.000 = 50.000 VND

10. Kết quả trả về

Khi tạo đơn hàng thành công, API trả về các thông tin quan trọng như:

amount – Tổng tiền đơn hàng.
qrCode – Chuỗi mã VietQR.
qrLink – Đường dẫn hiển thị mã QR.
qrImage – Hình ảnh QR dạng Base64 nếu được hỗ trợ.
transactionId.
transactionRefId.
orderId.
Thông tin tài khoản nhận tiền.

11. Callback giao dịch

Đối tác cần triển khai endpoint:

text

POST /<basepath>/bank/api/transaction-sync

Khi khách hàng thanh toán thành công, VietQR gửi thông tin giao dịch tới endpoint này.

Các dữ liệu quan trọng gồm:

text

{
  "bankaccount": "05643598501",
  "amount": 70000,
  "transType": "C",
  "content": "TT don pepsi08024",
  "transactionid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "transactiontime": 1757387821000,
  "referencenumber": "FT260909xxxxxx",
  "orderId": "pepsi08024"
}

Đối tác cần trả về HTTP 200 sau khi đã tiếp nhận và lưu giao dịch. Nếu VietQR không nhận được HTTP 200, hệ thống sẽ gửi lại callback.

12. Tự động phát hành hóa đơn

Sau khi giao dịch được xác nhận, hệ thống đối soát theo orderId.

Nếu tài khoản ngân hàng đã bật cấu hình xuất hóa đơn, hóa đơn điện tử sẽ được phát hành dựa trên:

Thông tin người mua.
Danh sách hàng hóa.
Số lượng.
Đơn giá.
Thuế suất.

Việc cấu hình xuất hóa đơn được thực hiện trên cổng VietQR.vn hoặc ứng dụng VietQR, không thực hiện trực tiếp thông qua AP

13. Callback hóa đơn

Đối tác triển khai:

text

POST /<basepath>/api/invoice-sync

Khi hóa đơn được phát hành, VietQR gửi kết quả về endpoint này.

orderId trong callback hóa đơn chính là mã liên kết với đơn hàng và callback giao dịch trước đó.

Đối tác nên sử dụng orderId để cập nhật trạng thái hóa đơn trên hệ thống nội bộ.

14. Tra cứu đơn hàng

Endpoint

text

POST /vqr/api/order/query

Request:

text

{
  "bankAccount": "05643598501",
  "orderId": "pepsi08024"
}

API trả về:

Trạng thái đơn hàng.
Trạng thái xuất hóa đơn.
invoiceId.
Tổng tiền.
Người mua.
Danh sách hàng hóa.
Thời gian tạo đơn.
Thời gian thanh toán.

15. Tra cứu hóa đơn

Endpoint

text

POST /vqr/api/invoice/query

Có thể tra cứu theo:

orderId
hoặc invoiceId

Ví dụ:

text

{
  "bankAccount": "05643598501",
  "orderId": "pepsi08024"
}

API dùng để lấy thông tin hóa đơn điện tử đã được lập từ đơn hàng.

16. Tải hóa đơn PDF

Endpoint

text

GET /vqr/api/invoice/export-pdf

API dùng để tải bản PDF của hóa đơn đã phát hành.

Ví dụ:

text

curl --location \
'https://api.vietqr.org/vqr/api/invoice/export-pdf?...' \
--header 'Authorization: Bearer <access_token>' \
--output hoa-don.pdf

17. Kiểm tra cấu hình xuất hóa đơn

Endpoint

text

GET /vqr/api/invoice-config/status

API này chỉ dùng để kiểm tra, không dùng để tạo hoặc chỉnh sửa cấu hình.

Các thông tin có thể kiểm tra:

enabled – Đã bật xuất hóa đơn hay chưa.
ready – Tài khoản đã sẵn sàng hay chưa.
bankAccount.
bankCode.
invoiceSerial.
fromTime.
toTime.
timeWaitingHour.

Trước khi đưa hệ thống vào vận hành, nên kiểm tra:

text

ready = true

18. Thuế suất

API hỗ trợ các giá trị:

`taxRate`	Thuế suất
`0`	0%
`5`	5%
`8`	8%
`10`	10%
`KCT`	Không chịu thuế
`KKKNT`	Không kê khai, nộp thuế
`KHAC`	Khác

Hệ thống nhận đơn giá đã bao gồm thuế và tự động tính giá trước thuế và tiền thuế theo từng dòng hàng.

Công thức:

text

lineAmountAfterTax = unitPriceAfterTax × quantity

linePreTax =
round(lineAmountAfterTax / (1 + taxRateFraction))

lineTax =
lineAmountAfterTax - linePreTax

19. Trạng thái đơn hàng

Status	Ý nghĩa
`PENDING`	Đã tạo đơn hàng, chờ thanh toán
`PAID`	Đã thanh toán
`EXPIRED`	Hết hạn thanh toán
`CANCELLED`	Đã hủy
`FAILED`	Thanh toán không thành công

20. Trạng thái xuất hóa đơn

invoiceStatus	Ý nghĩa
`NONE`	Chưa đưa vào luồng xuất hóa đơn
`WAITING`	Đang chờ phát hành
`ISSUED`	Đã phát hành
`FAILED`	Phát hành không thành công
`SKIPPED`	Không xuất hóa đơn

SKIPPED có thể xảy ra khi giao dịch nằm ngoài khung giờ xuất hóa đơn, chưa có ký hiệu hóa đơn hoặc cấu hình xuất hóa đơn đang tắt.

21. Trạng thái xử lý hóa đơn

Hệ thống hỗ trợ các trạng thái xử lý hóa đơn như:

Status	Ý nghĩa
`0`	Chưa gửi cơ quan thuế
`1`	Đã ký, đang chờ cơ quan thuế
`2`	Đang gửi cơ quan thuế
`3`	Đã cấp mã
`4`	Không cấp mã
`5`	Cơ quan thuế chấp nhận
`6`	Cơ quan thuế từ chối
`7`	Gửi lỗi
`8`	Ký lỗi

22. Các lỗi thường gặp

Mã lỗi	Ý nghĩa
`E46`	Dữ liệu hoặc tham số không hợp lệ
`E34`	`content` hoặc `orderId` sai định dạng
`E165`	`orderId` đã tồn tại
`E25`	Không tìm thấy tài khoản ngân hàng đã liên kết
`E77`	Tài khoản ngân hàng không khớp thông tin đăng ký
`E76`	Đối tác chưa được cấp quyền sử dụng dịch vụ
`E74`	Token không hợp lệ hoặc hết hạn
`E05`	Lỗi hệ thống

23. Điều kiện để tích hợp

Để sử dụng API Server xuất hóa đơn tự động, đối tác cần:

Có tài khoản Tingo Pay.
Liên kết tài khoản ngân hàng nhận tiền.
Được cấp thông tin kết nối API gồm username và password.
Triển khai API Get Token trên hệ thống đối tác.
Triển khai API Callback giao dịch.
Hoàn tất cấu hình xuất hóa đơn trên cổng VietQR.vn hoặc ứng dụng VietQR.
Liên kết nhà cung cấp hóa đơn điện tử.
Thiết lập ký hiệu hóa đơn.
Bật xuất hóa đơn cho tài khoản ngân hàng.
Thiết lập khung giờ và thời gian chờ phát hành.

24. Mô hình tích hợp tổng thể

text

┌──────────────────────┐
│  HỆ THỐNG ĐỐI TÁC    │
│ Website / App / POS  │
└──────────┬───────────┘
           │
           │ Get Token
           ▼
┌──────────────────────┐
│      TINGO PAY       │
│     VietQR API       │
└──────────┬───────────┘
           │
           │ Tạo đơn hàng
           │ + Items + Buyer
           ▼
┌──────────────────────┐
│      VIETQR          │
│   Mã thanh toán QR   │
└──────────┬───────────┘
           │
           │ Khách hàng thanh toán
           ▼
┌──────────────────────┐
│    NGÂN HÀNG         │
│   Giao dịch thành công│
└──────────┬───────────┘
           │
           │ Callback giao dịch
           ▼
┌──────────────────────┐
│      TINGO PAY       │
│ Đối soát orderId     │
└──────────┬───────────┘
           │
           │ Xuất hóa đơn tự động
           ▼
┌──────────────────────┐
│  HÓA ĐƠN ĐIỆN TỬ     │
│  Phát hành hóa đơn   │
└──────────┬───────────┘
           │
           │ Callback hóa đơn
           ▼
┌──────────────────────┐
│  HỆ THỐNG ĐỐI TÁC    │
│ Cập nhật trạng thái  │
└──────────────────────┘

Một API – nhiều nghiệp vụ

API Server giúp doanh nghiệp kết nối thanh toán và hóa đơn điện tử trong cùng một quy trình.

Tự động hóa

Từ lúc tạo đơn hàng, thanh toán thành công đến khi phát hành hóa đơn đều được liên kết tự động.

Đối soát chính xác

orderId là khóa liên kết xuyên suốt giữa đơn hàng, giao dịch và hóa đơn.

Dễ tích hợp

Hệ thống sử dụng HTTPS, JSON và Bearer Token, phù hợp để tích hợp với website, mobile app, POS, ERP, CRM và các hệ thống bán hàng.

Có callback theo thời gian thực

Đối tác không cần liên tục kiểm tra giao dịch. VietQR chủ động gửi callback khi giao dịch và hóa đơn có kết quả.

Chủ động tra cứu

Đối tác có thể tra cứu đơn hàng, hóa đơn và tải PDF khi cần.

26. Quy trình triển khai đề xuất

1. Đăng ký Tingo Pay

↓

2. Liên kết tài khoản ngân hàng

↓

3. Đăng ký thông tin API

↓

4. Nhận username/password

↓

5. Triển khai Get Token

↓

6. Triển khai Callback giao dịch

↓

7. Cấu hình hóa đơn điện tử

↓

8. Kiểm tra ready = true

↓

9. Kiểm thử trên môi trường Dev

↓

10. Chuyển sang môi trường Production

↓

11. Bắt đầu vận hành

API Server Tingo Pay – kết nối thanh toán và hóa đơn trên một quy trình

Tạo đơn hàng → Thanh toán VietQR → Xác nhận giao dịch → Phát hành hóa đơn → Callback → Tra cứu → Tải PDF

Đây là mô hình tích hợp API dành cho các đối tác muốn tự động hóa quy trình thu tiền và xuất hóa đơn điện tử ngay trên hệ thống bán hàng của mình.