Thu Hộ Qua Billing

Mô tả APIS đối tác cung cấp để tích hợp sử dụng dịch vụ thu hộ qua bill

1, Thông Tin Chung

1.1. Link API:

Endpoint (link API): ip:port/ context-root/function
Hoặc domain/context-root/function
Yêu cầu: context root phải unique để khai báo vào proxy ZENGI. (VD zengi-abc, trong đó abc là tên viết tắt của NCC)

1.2. Bảo Mật, Xác Thực:

• Whitelist IP
• Đối tác cung cấp cặp accessKey và secretKey để tạo chữ ký số
  Ví dụ:
  accessKey=1lCoX8CjcyH5A3KP
  secretKey=Cx4EDjpHknPAnYS3WmwqIJ6HGqzpXCaZ
  Message = accessKey + service_id + va
  X-Signature = HMAC_SHA256(secretKey, Message)
  

Ex Output X-Signature Hex: 48287707c1e78713614b5bff3314fe4f6c4944840dfb7913babd56d6dcab0ee4

2. Đặc tả các APIS

2.1. Vấn tin

a. Thông tin chung

Đường dẫn: Link_API/getbill
Phương thức: POST
Định dạng request: JSON
Định dạng response: JSON
Header:

No	Tên Header	Mô Tả	Ghi chú
1	Content-Type	application/json	Kiểu dữ liệu truyền
2	X-Signature	Chữ ký HMAC-SHA256	Được mã hoá HMAC_SHA256 từ chuỗi : accessKey + service_id + va

b. Request

{
    "va":"V3ZG20020000086ADD2",
    "service_id":"6B9002"
}

Tên	Kiểu	Bắt buộc	Mô tả
va	string	Y	TK Định Danh
service_id	string	Y	Mã của dịch vụ cung cấp

c. Response

Trường hợp thành công:

{
    "result_code": "000",
    "result_desc": "Success",
    "va": "V3ZG20020000086ADD2",
    "customer_name": "ZENGI",
    "type": "0",
    "amount": "79000",
    "service_id": "6B9002"
}

Tên	Kiểu	Bắt buộc	Mô tả
result_code	string	Y	Mã kết quả
result_desc	string	Y	Mô tả kết quả
va	string	Y	TK Định Danh
customer_name	string	Y	Tên NSD
type	string(1)	Y	default 0 (gạch nợ khớp số tiền), 1 (gạch nợ không khớp số tiền)
amount	string	Y	Số tiền

Trường hợp lỗi:

{
    "result_code": "017",
    "result_desc": "Không tìm thấy thông tin KH tại NCC"
}

{
    "result_code": "001",
    "result_desc": "Hóa đơn đã được thanh toán trước đó"
}

2.2. Gạch nợ

a. Thông tin chung

Đường dẫn: Link_API/paybill
Phương thức: POST
Định dạng request: JSON
Định dạng response: JSON
Header:

No	Tên Header	Mô Tả	Ghi chú
1	Content-Type	application/json	Kiểu dữ liệu truyền
2	X-Signature	Chữ ký HMAC-SHA256	Được mã hoá HMAC_SHA256 từ chuỗi : accessKey + va + transactionid + amount

b. Request

{
    "transactionid": "20251013000013",
    "transactiontime": "20251015003902",
    "referencenumber": "FT25132328062416",
    "amount": "79000",
    "va": "V3ZG20020000086ADD2",
    "narrative": "TTHDOL_FWEWQKKPUQKFKU_V3ZG20020000086ADD2_Khachhang:ZENGI_amount:26000_soGD:V3ZG20020000086ADD2@20250929000001_ky:20250929"
}

Tên	Kiểu	Bắt buộc	Mô tả
transactionid	string	Y	Số transaction sinh ra duy nhất trong hệ thống của Bank
transactiontime	string	Y	Thời gian gửi message (yyyyMMddhhmmss)
referencenumber	string	Y	Mã tham chiếu
bankAccount	string	N	Tài khoản nguồn
binCode	string	N	Bincode của ngân hàng quản lý tài khoản nguồn
transType	string	N	Loại giao dịch C - báo có, D - báo nợ
va	string	Y	Mã NSD/Mã đơn hàng
amount	string	Y	Số tiền
narrative	string	N	Mô tả
reciprocalAccount	string	N	Số tài khoản đối ứng
reciprocalBankCode	string	N	BinCode của ngân hàng quản lý tài khoản đối ứng

c. Response

Trường hợp thành công:

{
    "result_code": "000", 
    "result_desc": "Success"
}

Trường hợp thất bại:

{
    "result_code": "001",
    "result_desc": "Thiếu tham số đầu vào" 
}

{
    "result_code": "001",
    "result_desc": "Hóa đơn đã được thanh toán trước đó"
}