TÀI LIỆU ĐẶC TẢ · 2020-03-05 · Hệ thống các API trao đổi, chia sẻ dữ liệu...

1

VĂN PHÒNG CHÍNH PHỦ

TÀI LIỆU ĐẶC TẢ

API THANH TOÁN CHO BỘ/NGÀNH/ĐỊA PHƯƠNG

Ngày cập nhật 04/03/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 Quy trình thanh toán ................................................................................................... 4

1.3 Mô hình kết nối ........................................................................................................... 5

II. Đặc tả API và thông tin kết nối ...................................................................................... 6

2.1 Thông tin kết nối ......................................................................................................... 6

2.2 Giao tiếp giữa các hệ thống qua API .......................................................................... 7

2.3 Danh sách các API ...................................................................................................... 7

2.3.1 API Khởi tạo giao dịch ........................................................................................ 7

2.3.2 API Lấy biên lai thanh toán ............................................................................... 11

2.3.3 API Nhận kết quả giao dịch ............................................................................... 12

2.3.4 Nhận kết quả thanh toán trên giao diện (redirect) ............................................. 13

2.3.5 Hướng dẫn tạo chữ ký ....................................................................................... 14

III. DỮ LIỆU GIAO DỊCH .............................................................................................. 14

3.1 Mô tả ......................................................................................................................... 14

3.2 Định dạng file ........................................................................................................... 14

IV. BẢNG MÃ LỖI ........................................................................................................... 14

4.1.1 Bảng mã lỗi BNĐP trả về cho Payment Platform ............................................. 14

4.1.2 Bảng mã lỗi Payment Platform trả về cho BNĐP ............................................. 15

3

DANH MỤC CÁC TỪ VIẾT TẮT

STT VIẾT TẮT Ý NGHĨA

1. DVCQG Dịch vụ công Quốc gia

2. BNĐP Bộ/Ngành/Địa phương

3.

4.

4

I. Tổng quan

1.1 Mục tiêu

- Tài liệu hướng các Bộ/Ngành/Địa phương (BNĐP) kết nối đến hệ thống Payment

Platform của Cổng DVCQG

1.2 Quy trình 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 Bộ/Ngành/Địa phương 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. Đặc tả API và thông tin kết nối

2.1 Thông tin kết nối

Mục Diễn giải Ví dụ

Địa chỉ API khởi tạo Địa chỉ API Khởi

tạo giao dịch

http://ip-ss-

donvi:8080/XrdAdapter/RestService/forwar

d/payment-

api/rest/payment/v1.0.6/init?providerurl=htt

ps://apipc-

private.dichvucong.gov.vn&dstcode=VN:G

OV:000.00.00.G22:vpcpdvcprovider

Địa chỉ API Biên lai Địa chỉ API Biên

lai thanh toán

http://ip-ss-

donvi:8080/XrdAdapter/RestService/forwar

d/payment-

api/rest/payment/v1.0.6/get_bill??provideru

rl=https://apipc-

private.dichvucong.gov.vn&dstcode=VN:G

OV:000.00.00.G22:vpcpdvcprovider

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

Đầu mối hỗ trợ kết nối API: Nguyễn Mạnh Hùng – Phòng Giải pháp phần mềm – Công ty

Phần mềm VNPT Media, email: [email protected]

2.2 Giao tiếp giữa các hệ thống qua API

- Các API được cung cấp dưới dạng RESTful, hệ thống cung cấp các API sau:

o API Khởi tạo giao dịch

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

- BNĐP cần cung cấp API và return_url để nhận kết quả giao dịch từ Payment

Platform:

o API nhận kết quả giao dịch

o Return URL để chuyển hướng khách hàng sau khi thanh toán xong

2.3 Danh sách các API

2.3.1 API Khởi tạo giao dịch

URL: Xem bảng Thông tin kết nối

Request method: POST

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:

Thuộc tính đầu vào

Mã đối tác Được cung cấp khi

kết nôi 10025

Mã bí mật Được cung cấp khi

kết nôi 8ff35a26a44e57c5e1685f90e2580a0d

Tên trường

Kiểu dữ

liệu

Độ dài

tối đa Bắt buộc Mô tả

LoaiBanTin String 50 Bắt buộc INIT

PhienBan String 50 Bắt buộc 1.0.6

MaDoiTac Number 12 Bắt buộc Mã định danh đối tác

MaThamChieu String 255 Bắt buộc Mã giao dịch phía đối tác

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

LoaiHinhThanhToan String 50 Bắt buộc PAY

MaKenhThanhToan String 255 Bắt buộc Kênh thanh toán

1: WebApp - 2: MobileApp

mailto:[email protected]

8

✓ 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

MaLoaiHinhThuPhat String

255

Không bắt

buộc

Riêng với

MaDichVu

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ế

….

MaThietBi Number 5 Bắt buộc Mã thiết bị, mặc định truyền 1

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 Đơn vị tiền tệ VND hoặc USD

MaNganHang String 50 Bắt buộc Phương thức thanh toán, mặc định

truyền PAYMENT

ThongTinGiaoDich String 255 Bắt buộc Nội dung thanh toán

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 mã hóa của bản tin

9

Tên trường

Kiểu

dữ liệu

Độ dài

tối đa


là 1 – thu

phạt, giá trị

trường là bắt

buộc

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

phạt, giá trị

trường là bắt

buộc

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

KhoBac String 255

Không bắt

buộc

Riêng với

MaDichVu

Mã Kho bạc nhà nước thụ hưởng.

Danh sách do KBNN

quy định.

10

Tên trường

Kiểu

dữ liệu

Độ dài

tối đa


là 1 – thu

phạt, giá trị

trường là bắt

buộc

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ị

trường là bắt

buộc

Địa điểm vi phạm

TenNguoiViPham String 255

Không bắt

buộc

Riêng với

MaDichVu

là 1 – thu

phạt, giá trị

Tên người vi phạm

11

Tên trường

Kiểu

dữ liệu

Độ dài

tối đa


trường là bắt

buộc

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.3.2 API Lấy biên lai thanh toán

URL: Xem bảng Thông tin kết nối




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 URL để chuyển hướng người dung

MaXacThuc String 255 Bắt buộc Chuỗi mã hóa bản tin

Tên trường

Kiểu dữ

liệu

Độ dài


LoaiBanTin String 50 Bắt buộc GET_BILL

PhienBan String 50 Bắt buộc 1.0.6


12


2.3.3 API Nhận kết quả giao dịch


Content-type: application/x-www-form-urlencoded

Parameter name: data

Bản tin thông báo kết quả giao dịch có dạng như sau:

POST /merchant/confirm HTTP/1.1

HOST: example.com

Content-type: application/x-www-form-urlencoded

Content-length: 8

data={“LoaiBanTin”:”CONFIRM”,“MaLoi”:”00”,….}




ThoiGianGD String 50 Bắt buộc Thời gian thực hiện giao dịch

yyyyMMddHHmmss

MaXacThuc String 255 Bắt buộc Chuỗi mã hóa của bản tin

Tên trường Kiểu Độ dài Bắt buộc Mô tả



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


LoaiBanTin String 50 Bắt buộc CONFIRM

MaLoi String 10 Bắt buộc Kết quả thực hiện giao dịch



SoTien Number 12 Bắt buộc Số tiền

MaTienTe String 50 Bắt buộc Đơn vị tiền tệ VND hoặc USD

13


2.3.4 Nhận kết quả thanh toán trên giao diện (redirect)

Sau khi thanh toán xong, Khách hàng sẽ được redirect từ trang thanh toán của Payment

Platform về trang returnUrl của website BNĐP, returnUrl sẽ được truyền thêm các

tham số như sau: returnUrl?data=[MaThamChieu]&responseCode=[MaLoi]

&secureCode=[MaXacThuc]

BNĐP cung cấp returnUrl để Payment Platform cấu hình trên hệ thống.

MaGiaoDich String 255 Bắt buộc Mã giao dịch tại Payment Platform

MaNganHang String 50 Bắt buộc Phương thức thanh toán

ThoiGianGD String 50 Bắt buộc Thời gian giao dịch, định dạng

(yyyyMMddHHmmss)

ThongTinGiaoDic

h String 255 Bắt buộc Thông tin mô tả giao dịch

Token String 255 Bắt buộc Token thanh toán của người dùng

SoThe String 255 Bắt buộc Số thẻ

ThangThe String 50 Bắt buộc Tháng hết hạn của thẻ

NamThe String 50 Bắt buộc Năm hết hạn của thẻ


Tên trường

Kiểu dữ

liệu

Độ dài






ThoiGianGD String 50 Bắt buộc Thời gian tại phía đối tác

(yyyyMMddHHmmss)


14

2.3.5 Hướng dẫn tạo chữ ký

Chữ ký của bản được tính toán dựa trên thuật toán SHA-256, giá trị này được tính toán

dựa trên một chuỗi gồm các trường thông tin trong bản tin gửi sang Payment Platform,

nguyên tắc tạo chuỗi như sau:

- Thứ tự các trường chính là thứ tự từ trên xuống dưới trong các bảng mô tả

thông tin đầu vào

- Các trường được phân tách nhau bởi ký tự “|”

- Các trường được định nghĩa là không bắt buộc (Optional) thì giá trị bằng

rỗng

- Secret key luôn đứng cuối cùng

III. DỮ LIỆU GIAO DỊCH

3.1 Mô tả

Hàng ngày hệ thống Payment Platform sẽ sinh ra file dữ liệu giao dịch

(yyyymmdd_ECOM.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 đối tác

MaGiaoDich String Mã giao dịch phía Payment Platform

ThoiGianGD String Thời gian giao dịch

TrangThai String Trạng thái giao dịch

IV. BẢNG MÃ LỖI

4.1.1 Bảng mã lỗi BNĐP trả về cho Payment Platform

STT Mã lỗi Mô tả lỗi

API Nhận kết quả giao dịch

1 00 Thành công

15

4.1.2 Bảng mã lỗi Payment Platform trả về cho BNĐP

2 01 Không tìm thấy giao dịch

3 02 Giao dịch đã được xác nhận trước đó

4 08 Hệ thống bận hoặc timeout

5 97 Mã xác thực không hợp lệ

6 99 Các lỗi khác

STT Mã lỗi Mô tả lỗi

1 00 Thành công

2 01 Giao dịch thất bại

3 02 Dữ liệu không đúng định dạng

4 03 Mã giao dịch đã tồn tại

5 04 Timeout

6 05 Không tìm thấy dữ liệu

7 06 Lỗi hệ thống

8 07 Mã xác thực không đúng

9 08 Tài khoản đối tác đang bị khóa

10 09 Tài khoản đối tác không tồn tại

11 96 Hệ thống đang bảo trì

12 99 Lỗi không xác định

TÀI LIỆU ĐẶC TẢ · 2020-03-05 · Hệ thống các API trao đổi, chia sẻ dữ liệu...

Documents

Transcript of TÀI LIỆU ĐẶC TẢ · 2020-03-05 · Hệ thống các API trao đổi, chia sẻ dữ liệu...