1 VĂN PHÒNG CHÍNH PHỦ TÀI LIỆU ĐẶC TẢ API THANH TOÁN CHO NGÂN HÀNG Ngày cập nhật: 03/04/2020
1
VĂN PHÒNG CHÍNH PHỦ
TÀI LIỆU ĐẶC TẢ
API THANH TOÁN CHO NGÂN HÀNG
Ngày cập nhật: 03/04/2020
2
MỤC LỤC
MỤC LỤC ................................................................................................................................. 2
I. Tổng quan .......................................................................................................................... 4
1.1 Mục tiêu ...................................................................................................................... 4
1.2 Luồng thanh toán ........................................................................................................ 4
1.3 Mô hình kết nối ........................................................................................................... 5
II. Mô tả API .......................................................................................................................... 6
2.1 Mô tả cách giao tiếp .................................................................................................... 6
2.2 Mô tả chi tiết các API ................................................................................................. 6
2.2.1 API Khởi tạo giao dịch ........................................................................................ 6
2.2.2 API Truy vấn giao dịch ..................................................................................... 10
2.2.3 API Lấy biên lai thanh toán ............................................................................... 11
2.2.4 Nhận kết quả từ NH/TGTT ............................................................................... 12
III. ĐỐI SOÁT .................................................................................................................... 13
3.1 Mô tả ......................................................................................................................... 13
3.2 Định dạng file ........................................................................................................... 13
IV. BẢNG MÃ LỖI ............................................................................................................ 14
3
DANH MỤC CÁC TỪ VIẾT TẮT
STT VIẾT TẮT Ý NGHĨA
1. BNĐP Bộ/Ngành/Địa phương
2. NH/TGTT Ngân hàng/Trung gian thanh toán
3. PP Payment Platform
4. CIF Số định danh khách hàng tại Ngân hàng
5. KH Khách hàng
6. GD Giao dịch
4
I. Tổng quan
1.1 Mục tiêu
Tài liệu hướng dẫ các ngân hàng kết nối đến hệ thống Payment Platform của Cổng
DVCQG
1.2 Luồng thanh toán
Hình 1: Quy trình thanh toán
5
1.3 Mô hình kết nối
Hình 2: Mô hình kết nối
Hệ thống các API trao đổi, chia sẻ dữ liệu cần đi qua Nền tảng tích hợp, chia sẻ
dữ liệu (VDXP) được phát triển từ Trục liên thông văn bản quốc gia, các nội dung kỹ
thuật bao gồm:
- Các ngân hàng, trung gian thanh toán cần liên hệ với VPCP để xin kết nối thông
đến mạng truyền số liệu chuyên dụng – CPNET theo mô hình như ở dưới:
6
- Thiết lập, cài đặt máy chủ bảo mật kết nối (SS – Secure Server) để kết nối với
Cổng Dịch vụ công quốc gia hoặc thiết lập máy chủ bảo mật mới theo tài liệu hướng
dẫn tại support.chinhphu.vn.
- Cấu hình máy chủ bảo mật kết nối với Cổng dịch vụ công quốc gia theo hướng
dẫn của Văn phòng Chính phủ, tài liệu tại: https://dichvucong.gov.vn/p/home/huong-
dan-bo-nganh-dia-phuong.html
II. Mô tả API
2.1 Mô tả cách giao tiếp
- Ngân hàng cung cấp các API Restful sau:
o API Khởi tạo giao dịch
o API Truy vấn giao dịch
o API Lấy biên lai thanh toán
- PP cung cấp <return_url > để ngân hàng/TTTT trả kết quả giao dịch đồng thời
chuyển hướng khách hàng về lại hệ thống PP.
2.2 Mô tả chi tiết các API
2.2.1 API Khởi tạo giao dịch
Request method: POST
Header: Content-type = application/json
Tham số đầu vào và đầu ra là một đối tượng JSON với các thuộc tính dưới đây:
7
• Thuộc tính đầu vào
✓ Các thông tin chi tiết trong trường ThongTinBienLai:
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa
Bắt buộc Mô tả
MaDichVu Number 5 Bắt buộc
Mã dịch vụ
1: Thu phạt
2: Thu phí, lệ phí
3: Thu thuế
TKThuHuong String 255 Không bắt
buộc
Số tài khoản ngân hàng thụ
hưởng
MaNHThuHuong String 255 Không bắt
buộc Mã ngân hàng thụ hưởng
TenTKThuHuong String 255
Không bắt
buộc
Tên chủ tài khoản
LoaiPhiTTHC String 255 Không bắt
buộc Mã loại phí thủ tục hành chính
TenLoaiPhiTTHC String 255 Không bắt
buộc
Tên loại phí thủ tục hành chính
Tên trường
Kiểu dữ
liệu
Độ dài
tối đa Bắt buộc Mô tả
MaDoiTac String 255 Bắt buộc Mã định danh đối tác tại
NH/TGTT
MaThamChieu String 255 Bắt buộc Mã tham chiếu PP gửi sang
NH/TGTT
SoTien String 50 Bắt buộc Số tiền thanh toán
PhiChuyenPhat String 50 Không bắt
buộc Phí chuyển phát
NgonNgu String 10 Bắt buộc Ngôn ngữ: vi-VN/en-US; mặc
định là vi-VN
MaTienTe String 50 Bắt buộc VND
ThongTinGiaoDich String 255 Bắt buộc Mô tả giao dịch
ThongTinBienLai Object Bắt buộc Thông tin để xuất biên lai và
hạch toán
ThoiGianGD String 50 Bắt buộc Thời gian giao dịch, định dạng
yyyyMMddHHmmss
Ip String 50 Bắt buộc IP của người dùng
MaXacThuc String 255 Bắt buộc Chuỗi chữ ký của bản tin
8
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa
Bắt buộc Mô tả
MaLoaiHinhThuPhat String
255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Mã loại hình thu phạt theo quy
định của KBNN
01: Các khoản phạt của tòa án
02: Phạt vi phạm giao thông
03: Phạt VPHC lĩnh vực thuế
….
TenLoaiHinhThuPhat String
255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Tên loại hình thu phạt theo quy
định của KBNN
(Tương ứng theo bảng mô tả
trường MaLoaiHinhThuPhat)
NoiDungThanhToan String 255 Bắt buộc Nội dung phạt/Thanh toán phí, lệ
phí/Thanh toán tiền Thuế,
HoTenNguoiNop String 255 Bắt buộc Họ và tên người nộp
SoCMNDNguoiNop String 255 Bắt buộc Số CMND/MST/HC
DiaChiNguoiNop String 255 Bắt buộc Địa chỉ của người nộp
HuyenNguoiNop String 255 Không bắt
buộc Huyện của người nộp
TinhNguoiNop String 255 Không bắt
buộc Tỉnh của người nộp
MaCoQuanQD String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Mã đơn vị ra quyết định xử
phạt/Đơn vị giải quyết thủ tục
dịch vụ công
TenCoQuanQD String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
Tên đơn vị ra quyết định xử
phạt/Đơn vị giải quyết thủ tục
dịch vụ công
9
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa
Bắt buộc Mô tả
phạt, giá trị
trường là bắt
buộc
KhoBac String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Mã Kho bạc nhà nước thụ hưởng.
Danh sách do KBNN
quy định.
NgayQD String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Ngày ra quyết định xử phạt/Thu
phí,lệ phí
SoQD String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Số Quyết định xử phạt/Thông
báo
ThoiGianViPham String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Thời gian vi phạm
DiaDiemViPham String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
Địa điểm vi phạm
10
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa
Bắt buộc Mô tả
trường là bắt
buộc
TenNguoiViPham String 255
Không bắt
buộc
Riêng với
MaDichVu
là 1 – thu
phạt, giá trị
trường là bắt
buộc
Tên người vi phạm
TaiKhoanThuNSNN String 255
Không bắt
buộc
Tài khoản của đơn vị ra quyết
định/thông báo mở tại KBNN
DSKhoanNop Object Bắt buộc Danh sách các Nội dung khoản
nộp/Mã định danh hồ sơ
✓ Các trường thông tin chi tiết trong DSKhoanNop:
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa
Bắt buộc Mô tả
NoiDung String 255 Bắt buộc Nội dung các khoản nộp/Mã định
danh hồ sơ
SoTien String 255 Bắt buộc Số tiền
Thuộc tính đầu ra
2.2.2 API Truy vấn giao dịch
Request method: POST
Header: Content-type = application/json
Tham số đầu vào và đầu ra là một đối tượng JSON với các thuộc tính dưới đây:
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa Bắt buộc Mô tả
MaLoi String 10 Bắt buộc Mã lỗi
MoTaLoi String 255 Bắt buộc Mô tả lỗi
UrlThanhToan String 255 Bắt buộc
Đường dẫn để chuyển hướng
người dùng đến trang thanh toán
của ngân hàng
MaXacThuc String 255 Bắt buộc Chuỗi chữ ký bản tin
11
• Thuộc tính đầu vào
• Thuộc tính đầu ra
2.2.3 API Lấy biên lai thanh toán
Request method: POST
Header: Content-type = application/json
Tham số đầu vào và đầu ra là một đối tượng JSON với các thuộc tính dưới đây:
Tên trường
Kiểu dữ
liệu
Độ dài
tối đa Bắt buộc Mô tả
MaDoiTac String 255 Bắt buộc Mã định danh đối tác tại
NH/TGTT
MaThamChieu String 255 Bắt buộc Mã tham chiếu PP gửi sang
NH/TGTT
ThoiGian String 50 Bắt buộc Thời gian gửi yêu cầu truy vấn,
định dạng yyyyMMddHHmmss
MaXacThuc String 255 Bắt buộc Chuỗi chữ ký của bản tin
Tên trường
Kiểu dữ
liệu
Độ dài
tối đa Bắt buộc Mô tả
MaLoi String 10 Bắt buộc Mã lỗi
MoTaLoi String 255 Bắt buộc Mô tả lỗi
MaDoiTac String 255 Bắt buộc Mã định danh đối tác tại
NH/TGTT
MaThamChieu String 255 Bắt buộc Mã tham chiếu PP gửi sang
NH/TGTT
MaGD String 255 Bắt buộc Mã giao dịch tại NH/TGTT
TrangThaiGD Number 10 Bắt buộc Trạng thái giao dịch
SoTien String 50 Bắt buộc Số tiền thanh toán
NgonNgu String 10 Bắt buộc Ngôn ngữ
MaTienTe String 50 Bắt buộc Mã tiền tệ
ThoiGian String 50 Bắt buộc Thời gian phản hồi, định dạng
yyyyMMddHHmmss
MaXacThuc String 255 Bắt buộc Chuỗi chữ ký của bản tin
12
• Thuộc tính đầu vào
• Thuộc tính đầu ra
2.2.4 Nhận kết quả từ NH/TGTT
Sau khi Khách hàng thanh toán xong, hệ thống NH/TGTT sẽ điều hướng Khách hàng
về <return_url> của PP thông qua phương thức HTTP POST, đồng thời trả về bản tin
JSON chứa kết quả giao dịch dưới dạng Base64-encoded trong tham số ‘data’.
Ví dụ bản tin trước khi encode Base64: {
"MaLoi": "00",
"MaDoiTac": "12345",
"MaGD": "20200109085736",
"MaXacThuc":"auoTuFVysdlh0QsNVUj4PF3MIThKuHOkPNYSljpwH/K3EWpXZUlUFC8
yo7DzCuFqfy7M3sYnnQd0MWIvLanCbe+YBtaNnudnH4+E1E0c5WZ4AiOonTNwiXbjSWD
Iqg9f5eQCejo13KnCeBH2Fq2S5pMBmqvdPGUf4oNhI98zp2aLHU4IP2FFJS6dMQ0EJx/
tAYPs+pZFEdG/ow15iuh13A2c7a608w4M8PGu8QWp2ivgatSk6oz38rTgUxGiUFNPz+j
HA6SOQpnpOw2s87chRy2DwYgq0PEGvWCh1x8NJmV49d8TDnf4pYPIdc1cmO8zQeaPBw9
9SoLY6stCJH663A=="
}
• Thuộc tính đầu vào
Tên trường
Kiểu dữ
liệu
Độ dài
tối đa Bắt buộc Mô tả
MaDoiTac String 1,255 Bắt buộc Mã định danh đối tác tại
NH/TGTT
MaThamChieu String 1,255 Bắt buộc Mã tham chiếu PP gửi sang
NH/TGTT
ThoiGianGD String 1,50 Bắt buộc Thời gian thực hiện giao dịch
yyyyMMddHHmmss
MaXacThuc String 1,255 Bắt buộc Chuỗi chữ ký của bản tin
Tên trường
Kiểu dữ
liệu
Độ dài
tối đa Bắt buộc Mô tả
MaLoi String 10 Bắt buộc Mã lỗi
MoTaLoi String 255 Bắt buộc Mô tả lỗi
UrlBienLai String 255 Bắt buộc Đường dẫn lưu file Biên lai thanh
toán
Tên trường
Kiểu
dữ liệu
Độ dài
tối đa Bắt buộc Mô tả
MaLoi String 10 Bắt buộc Trạng thái giao dịch (00=Thành
công)
13
III. ĐỐI SOÁT
3.1 Mô tả
Hàng ngày hệ thống Payment Platform của VNPT sẽ sinh ra file dữ liệu giao dịch
(yyyymmdd_ECOM_HCC.csv) trong ngày (ngày T) từ 00:00 đến 23h:59 bao gồm các
giao dịch thành công lên thư mục SFTP đã thống nhất giữa các bên trước 08h00 ngày
hôm sau (ngày T+1).
3.2 Định dạng file
Định dạng dòng dữ liệu: Các trường được đặt cách nhau bởi dấu #
Tham số Kiểu Mô tả
MaThamChieu String Mã giao dịch phía PP
ThoiGianGD String Thời gian giao dịch
TrangThaiGD String Trạng thái giao dịch
Mota String Mô tả trạng thái GD
MaDoiTac String 255 Bắt buộc Mã định danh đối tác tại
NH/TGTT
MaGD String 255 Bắt buộc Mã GD tại NH/TGTT
MaXacThuc String 255 Bắt buộc Chuỗi chữ ký của bản tin
14
IV. BẢNG MÃ LỖI
Mã lỗi Mô tả
00 Thành công
01 Giao dịch thất bại
02 Dữ liệu không đúng định dạng
03 Mã giao dịch đã tồn tại
04 Timeout
05 Không tìm thấy dữ liệu
06 Lỗi hệ thống
07 Chữ ký không đúng
08 Mã đối tác đang bị khóa
09 Mã đối tác không tồn tại
96 Hệ thống đang bảo trì
99 Lỗi không xác định