tÀi liỆu ĐẶc tẢ · 2020-01-10 · 4.1.2 bảng mã lỗi payment platform trả về cho...

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

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

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

2.2.4 Hướng dẫn tạo chữ ký ....................................................................................... 10

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

3.1 Mô tả ......................................................................................................................... 11

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

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

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

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

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 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 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. Mô tả API

2.1 Mô tả cách giao tiếp

- 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.2 Mô tả chi tiết các API

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

URL: {api_base_url}/init

Request method: POST

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

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

Thuộc tính đầu ra

Name Type Length Mandatory

/optional Comments

LoaiBanTin String 1,50 M INIT

PhienBan String 1,50 M 1.0.6

MaDoiTac Number 1,12 M Mã định danh đối tác

MaThamChieu String 1,255 M Mã giao dịch phía đối tác

SoTien String 1,50 M Số tiền thanh toán

LoaiHinhThanhToan String 1,50 M PAY

MaKenhThanhToan String 0,255 M Kênh thanh toán

1: WebApp - 2: MobileApp

MaThietBi Number 0,12 M Mã thiết bị, mặc định truyền 1

NgonNgu String 1,10 M Ngôn ngữ: vi-VN/en-US; mặc định

là vi-VN

MaTienTe String 1,50 M Đơn vị tiền tệ VND hoặc USD

MaNganHang String 1,50 M Phương thức thanh toán

ThongTinGiaoDich String 1,255 M Mô tả giao dịch

LoaiXacThuc String 1,255 M Phương thức xác thực:

1: Thẻ, 2=tài khoản, 3=CIF

ThongTinBienLai String 1,4000 M Thông tin để xuất biên lai và hạch

toán

ThongTinTaiKhoan String 1,4000 M Thông tin tài khoản

ThoiGianGD String 1,50 M Thời gian giao dịch, định dạng

yyyyMMddHHmmss

Ip String 1,50 M IP của người dùng

MaXacThuc String 1,255 M Chuỗi mã hóa của bản tin


/optional Comments

MaLoi String 1,10 M Mã lỗi

8

Các thông tin chi tiết trong trường ThongTinBienLai:

Name Type Comments Mandatory

/optional

TKThuHuong String Tài khoản ngân hàng thụ hưởng M

MaNHThuHuong String Mã ngân hàng thụ hưởng M

TenTKThuHuong String Tên chủ tài khoản của ngân hàng

thụ hưởng M

MaHoSo String Mã hồ sơ M

LoaiPhiTTHC String Loại phí thủ tục hành chính M

NoiDungThanhToan String Nội dung thanh toán M

Các thông tin chi tiết trường ThongTinTaiKhoan

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

URL: {api_base_url}/get_bill




MoTaLoi String 1,255 M Mô tả lỗi

UrlThanhToan String 1,255 M URL để chuyển hướng người dung

MaXacThuc String 1,255 M Chuỗi mã hóa bản tin


/optional Comments

SoCMND String 1,255 M Số CMND/Hộ chiếu

TenTaiKhoan String 1,255 M Họ tên KH

NgaySinh String 1,255 M Ngày sinh KH

SoTaiKhoan String 1,255 M Số TK khách hàng

SoThe String 1,255 M Số thẻ ATM của KH

NgayHieuLuc String 1,255 M Ngày hết hạn thẻ

SoDienThoai String 1,255 M SĐT đăng ký SMS tại ngân hàng


/optional Comments

LoaiBanTin String 1,50 M GET_BILL

9


2.2.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”,….}



PhienBan String 1,50 M 1.0.6



ThoiGianGD String 1,50 M Thời gian thực hiện giao dịch

yyyyMMddHHmmss

MaXacThuc String 1,255 M Chuỗi mã hóa của bản tin


/optional Comments



NoiDungHoaDon String O Nội dung dạng Base64 của file Biên

lai


/optional Comments

LoaiBanTin String 1,50 M CONFIRM

MaLoi String 1,10 M Kết quả thực hiện giao dịch


10


2.2.4 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ự “|”


SoTien Number 1,8 M Số tiền

MaTienTe String 1,50 M Đơn vị tiền tệ VND hoặc USD

MaGiaoDich String 1,255 M Mã giao dịch tại Payment Platform

MaNganHang String 1,50 M Phương thức thanh toán

ThoiGianGD String 1,50 M Thời gian giao dịch, định dạng

(yyyyMMddHHmmss)

ThongTinGiaoDich String 1,255 M Thông tin mô tả giao dịch

Token String 1,255 M Token thanh toán của người dùng

SoThe String 1,255 M Số thẻ

ThangThe String 1,50 M Tháng hết hạn của thẻ

NamThe String 1,50 M Năm hết hạn của thẻ



/optional Comments





ThoiGianGD String 1,50 M Thời gian tại phía đối tác

(yyyyMMddHHmmss)


11

- 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

Định dạng dòng kết thúc: Checksum tạo bởi các transactionId của các dòng dữ liệu

theo thứ tự từ trên xuống dưới

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 Notify

1 00 Thành công

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

3 02 Giao dịch đã confirm

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

12

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

5 97 Chữ ký không hợp lệ

6 99 Các lỗi khác

No 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 Chữ ký 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-01-10 · 4.1.2 bảng mã lỗi payment platform trả về cho...

Documents