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 + customer_id
  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 + customer_id

b. Request

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

Tên	Kiểu	Bắt buộc	Mô tả
customer_id	string	Y	Mã NSD/Mã đơn hàng (Kèm mã đầu 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",
    "customer_id": "V3ZG20020000086ADD2",
    "customer_name": "pip22",
    "customer_addr": "",
    "bill_id": "V3ZG20020000086ADD2",
    "type": "1",
    "total_amount": "79000",
    "data": {
        "period": "Test 2",
        "data": [
            {
                "bill_id": "V3ZG20020000086ADD2",
                "amount": "79000",
                "remark": "Test 2"
            }
        ]
    }
}

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ả
customer_id	string	Y	Mã NSD/Mã đơn hàng (Kèm mã đầu TK Định Danh)
customer_name	string	Y	Tên NSD
customer_addr	string	N	Địa chỉ NSD
bill_id	string	Y	Bill Id
type	string(1)	Y	default 1 (gạch nợ khớp số tiền)
total_amount	string	Y	Số tiền
data	list	Y
period	string	Y	Chu kỳ hoặc kỳ thanh toán mà dữ liệu thuộc về, nếu thanh toán cho 1 bill thì = remark
bill_id	string	Y	Mã duy nhất ứng với một khoản nợ
amount	string	Y	Số tiền
remark	string	N	Mô tả Nên theo cấu trúc sau: Số tài khoản định danh (giống customer-ID) + Nội dung thanh toán + Bill ID

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 + customer_id + trans_id + bill_id + amount

b. Request

{
    "bill_id": "V3ZG20020000086ADD2",
    "trans_date": "20251015003902",
    "amount": "79000",
    "trans_id": "20251013000013",
    "customer_id": "V3ZG20020000086ADD2",
    "remark": "TTHDOL_FWEWQKKPUQKFKU_V3ZG20020000086ADD2_Khachhang:pip22_amount:26000_soGD:V3ZG20020000086ADD2@20250929000001_ky:20250929"
}

Tên	Kiểu	Bắt buộc	Mô tả
trans_id	string	Y	Số transaction sinh ra duy nhất trong hệ thống của Bank
trans_date	string	Y	Thời gian gửi message (yyyyMMddhhmmss)
customer_id	string	Y	Mã NSD/Mã đơn hàng
bill_id	string	Y	Mã hóa đơn cần gạch nợ lấy từ hàm vấn tin
amount	string	Y	Số tiền
remark	string	N	Mô tả

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 đó"
}