Ancarat × BIDV — API Documentation

Ancarat × BIDV
Balance Notification

Dịch vụ nhận biến động số dư (BĐSD) từ BIDV qua luồng H2H — mã hóa OpenPGP, xác thực Basic Auth, lưu trữ cơ sở dữ liệu.

● Live v0.1.0 OpenPGP

Xác thực (Authentication)

BIDV xác thực bằng Basic Auth khi gọi API của chúng ta.

Basic Auth (BIDV → Ancarat)

HTTP header:

Authorization: Basic <base64(username:password)>

Username và password do Ancarat cấp cho BIDV. Được cấu hình qua biến môi trường BIDV_BASIC_AUTH_USERNAME và BIDV_BASIC_AUTH_PASSWORD.

REQUESTID Header

BIDV gửi kèm header để trace log:

REQUESTID: 20220510155610517-7babdf6a-691c-407d-9b5f-fd0f6320037f

Được lưu vào cơ sở dữ liệu (trường bidv_request_id) và log để đối soát.

Mã hóa PGP (OpenPGP Encryption)

BIDV mã hóa dữ liệu giao dịch bằng OpenPGP trước khi gửi.

Quy trình mã hóa

1. Ancarat tạo cặp khóa PGP (RSA 2048+)
2. Gửi public key cho BIDV
3. BIDV mã hóa dữ liệu JSON bằng public key
4. Base64 encode dữ liệu đã mã hóa
5. Gửi trong trường "data" của request body
6. Ancarat giải mã bằng private key

Private key lưu tại certs/pgp-private-key.asc (GITIGNORED). Public key tại certs/pgp-public-key.asc.

POST

Balance Notification (Biến Động Số Dư)

/api/v1/bidv/ancarat/notify

↙ Inbound — BIDV gọi Ancarat

BIDV gửi thông tin biến động số dư (ghi nợ/ghi có) trên tài khoản. Dữ liệu được mã hóa PGP, giải mã và lưu vào cơ sở dữ liệu.

BIDV
(encrypt)

→

Ancarat
(auth)

→

PGP
(decrypt)

→

Ancarat
(dedup)

→

Cơ sở
dữ liệu

BIDV có cơ chế retry giao dịch. Hệ thống tự động loại trùng bằng cặp (accountNo, refNo, seq).

Request Headers

Header	Value	Description
Authorization	Basic <base64>	Basic Auth credentials
Content-Type	application/json	JSON body
REQUESTID	String	Mã trace log từ BIDV

Request Body

Field	Type	Required	Description
bankCode	Literal["BIDV"]	Required	Nguồn dữ liệu (mặc định "BIDV")
data	String (max 10MB)	Required	Dữ liệu giao dịch đã được BIDV mã hóa PGP + Base64

Response

Field	Type	Description
errorCode	String	"000" = Thành công
errorDesc	String	Mô tả kết quả

HTTP status luôn trả về 200. Kết quả thành công/thất bại được xác định bởi errorCode trong body.

Transaction Fields (28 trường)

Nội dung JSON sau khi giải mã trường "data". Có thể là 1 object hoặc 1 array nhiều giao dịch.

#	Field	Type	Required	Description
1	transDate	String(6)	M	Ngày hạch toán (ddmmyy). VD: "120126" = 12/01/2026
2	transTime	String(6)	M	Giờ hạch toán (HH24MISS). VD: "101804"
3	accountNo	String	M	Số tài khoản nhận biến động số dư
4	dorc	Literal["C","D"]	M	C = Credit (ghi có), D = Debit (ghi nợ)
5	currency	String	M	Loại tiền (VND)
6	amount	String (digits)	M	Số tiền giao dịch (VND, số nguyên, không có thập phân)
7	remark	String	O	Nội dung giao dịch
8	refNo	String	M	Số tham chiếu (số hạch toán tại Core BIDV)
9	frBankCode	String	O	Mã ngân hàng gửi
10	frAccName	String	O	Tên tài khoản gửi
11	frAccNo	String	O	Số tài khoản gửi
12	frBankName	String	O	Tên ngân hàng gửi
13	seq	String	M	Số thứ tự giao dịch tại BIDV
14	endBal	String	O	Số dư sau giao dịch
15	channelRef	String	O	Số tham chiếu kênh
16	channelID	String	O	Mã kênh thanh toán
17	toBankCode	String	O	Mã ngân hàng nhận
18	toAccName	String	O	Tên tài khoản nhận
19	toAccNo	String	O	Số tài khoản nhận
20	toBankName	String	O	Tên ngân hàng nhận
21	va	String	O	Số tài khoản định danh (Virtual Account)
22	transCode	String	O	Mã loại giao dịch theo BIDV
23	businessDate	String	O	Ngày tạo giao dịch
24-28	ext1 – ext5	String	O	Trường mở rộng 1-5

Loại trùng (Deduplication)

BIDV có cơ chế retry khi gửi thông tin không thành công. Hệ thống sử dụng unique index để chống trùng.

Khóa duy nhất (Unique Key)

(accountNo, refNo, seq)

Chỉ mục duy nhất (unique compound index) trên cơ sở dữ liệu. Giao dịch trùng sẽ tự động bỏ qua, trả về errorCode "000".

Đối soát dữ liệu: Hệ thống khách hàng có thể vấn tin lịch sử / sao kê tài khoản từ BIDV (theo luồng Inbound) để đảm bảo đầy đủ dữ liệu.

GET

Health Check

/health

Kiểm tra trạng thái hệ thống: cơ sở dữ liệu và khóa PGP.