tÀi liỆu ĐẶc tẢ

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:

https://dichvucong.gov.vn/p/home/huong-dan-bo-nganh-dia-phuong.html

https://dichvucong.gov.vn/p/home/huong-dan-bo-nganh-dia-phuong.html

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


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


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


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


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




Tên trường

Kiểu

dữ liệu

Độ dài


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 ra

2.2.3 API Lấy biên lai thanh toán




Tên trường

Kiểu dữ

liệu

Độ dài



NH/TGTT


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


Tên trường

Kiểu dữ

liệu

Độ dài





NH/TGTT


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


12


• 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=="

}


Tên trường

Kiểu dữ

liệu

Độ dài


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




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


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


NH/TGTT

MaGD String 255 Bắt buộc Mã GD tại NH/TGTT


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

tÀi liỆu ĐẶc tẢ

Documents