TÀI LIỆU ĐẶC TẢ API THANH TOÁN CHO BỘ/NGÀNH/ĐỊA PHƯƠNG

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 13/03/2020 MỤC LỤC MỤC LỤC Tổng quan I 1.1 Mục tiêu 1.2 Quy trình tốn 1.3 Mô hình kết nối II Đặc tả API thông tin kết nối 2.1 Thông tin kết nối 2.2 Giao tiếp hệ thống qua API 2.3 Danh sách API 2.3.1 API Khởi tạo giao dịch 2.3.2 API Lấy biên lai toán 11 2.3.3 API Nhận kết giao dịch 12 2.3.4 Nhận kết toán giao diện (redirect) 13 2.3.5 Hướng dẫn tạo chữ ký 14 DỮ LIỆU GIAO DỊCH 14 III 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ả cho Payment Platform 14 4.1.2 Bảng mã lỗi Payment Platform trả cho BNĐP 15 DANH MỤC CÁC TỪ VIẾT TẮT STT VIẾT TẮT Ý NGHĨA DVCQG Dịch vụ công Quốc gia BNĐP Bộ/Ngành/Địa phương I Tổng quan 1.1 Mục tiêu - Tài liệu hướng Bộ/Ngành/Địa phương (BNĐP) kết nối đến hệ thống Payment Platform Cổng DVCQG 1.2 Quy trình tốn Hình 1: Quy trình tốn 1.3 Mơ hình kết nối Hình 2: Mơ hình kết nối Hệ thống API trao đổi, chia sẻ liệu cần qua Nền tảng tích hợp, chia sẻ liệu (VDXP) phát triển từ Trục liên thông văn quốc gia, 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ơ dưới: - 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 thiết lập máy chủ bảo mật theo tài liệu hướng dẫn 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 Văn phịng Chính phủ, tài liệu tại: https://dichvucong.gov.vn/p/home/huongdan-bo-nganh-dia-phuong.html II Đặc tả API thông tin kết nối 2.1 Thông tin kết nối Mục Diễn giải Địa API khởi tạo Địa API Khởi tạo giao dịch Địa API Biên lai Địa API Biên lai tốn Ví dụ http://ip-ssdonvi:8080/XrdAdapter/RestService/forwar d/paymentapi/rest/payment/v1.0.6/init?providerurl=htt ps://apipcprivate.dichvucong.gov.vn&dstcode=VN:G OV:000.00.00.G22:vpcpdvcprovider http://ip-ssdonvi:8080/XrdAdapter/RestService/forwar d/paymentapi/rest/payment/v1.0.6/get_bill?providerurl =https://apipcprivate.dichvucong.gov.vn&dstcode=VN:G OV:000.00.00.G22:vpcpdvcprovider Mã đối tác Mã bí mật Được cung cấp kết nôi Được cung cấp kết nôi 10025 8ff35a26a44e57c5e1685f90e2580a0d Đầ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: hungnguyenmanh@vnpt.vn 2.2 Giao tiếp hệ thống qua API - Các API cung cấp dạng RESTful, hệ thống cung cấp API sau: - o API Khởi tạo giao dịch o API Lấy biên lai toán BNĐP cần cung cấp API return_url để nhận kết giao dịch từ Payment Platform: o API nhận kết giao dịch o Return URL để chuyển hướng khách hàng sau toán xong 2.3 Danh sách 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 đầu đối tượng JSON với thuộc tính đây: Thuộc tính đầu vào Tên trường Kiểu 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 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 toán 1: WebApp - 2: MobileApp MaThietBi Number Bắt buộc Mã thiết bị, mặc định truyền NgonNgu String 10 Bắt buộc MaTienTe String 50 Bắt buộc Đơn vị tiền tệ VND USD MaNganHang String 50 Bắt buộc Phương thức toán, mặc định truyền PAYMENT ThongTinGiaoDich String 255 Bắt buộc Nội dung toán ThongTinBienLai Object ThoiGianGD String 50 Bắt buộc Ip String 50 Bắt buộc IP người dùng MaXacThuc String 255 Bắt buộc Chuỗi mã hóa tin Ngơn ngữ: vi-VN/en-US; mặc định vi-VN Thơng tin để xuất biên lai hạch tốn Thời gian giao dịch, định dạng yyyyMMddHHmmss Bắt buộc ✓ Các thông tin chi tiết trường ThongTinBienLai: Tên trường Độ dài tối đa Kiểu liệu MaDichVu Number TKThuHuong String 255 MaNHThuHuong String 255 TenTKThuHuong String 255 LoaiPhiTTHC String 255 TenLoaiPhiTTHC String 255 Bắt buộc Mô tả Mã dịch vụ 1: Thu phạt Bắt buộc 2: Thu phí, lệ phí 3: Thu thuế Khơng bắt Số tài khoản ngân hàng thụ buộc hưởng Không bắt Mã ngân hàng thụ hưởng buộc Không buộc Không buộc Không buộc bắt Tên chủ tài khoản bắt Mã loại phí thủ tục hành bắt Tên loại phí thủ tục hành Mã loại hình thu phạt theo quy định KBNN MaLoaiHinhThuPhat String 255 Không bắt buộc Riêng với MaDichVu 01: Các khoản phạt tòa án 02: Phạt vi phạm giao thông 03: Phạt VPHC lĩnh vực thuế … Tên trường Kiểu liệu Độ dài tối đa Bắt buộc Mô tả – thu phạt, giá trị trường bắt buộc 255 Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc String 255 Bắt buộc HoTenNguoiNop SoCMNDNguoiNop DiaChiNguoiNop String String String 255 255 255 HuyenNguoiNop String 255 TinhNguoiNop String 255 Bắt buộc Bắt buộc Bắt buộc Không bắt buộc Không bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu TenLoaiHinhThuPhat String NoiDungThanhToan MaCoQuanQD TenCoQuanQD KhoBac String String String 255 255 255 Tên loại hình thu phạt theo quy định KBNN (Tương ứng theo bảng mơ tả trường MaLoaiHinhThuPhat) Nội dung phạt/Thanh tốn phí, lệ phí/Thanh tốn tiền Thuế, Họ tên người nộp Số CMND/MST/HC Địa người nộp Huyện người nộp Tỉnh người nộp Mã đơn vị định xử phạt/Đơn vị giải thủ tục dịch vụ công Tên đơn vị định xử phạt/Đơn vị giải thủ tục dịch vụ công Mã Kho bạc nhà nước thụ hưởng Danh sách KBNN quy định Tên trường Kiểu liệu Độ dài tối đa NgayQD String 255 SoQD String 255 ThoiGianViPham String 255 DiaDiemViPham String 255 TenNguoiViPham String 255 Bắt buộc – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị trường bắt buộc Không bắt buộc Riêng với MaDichVu – thu phạt, giá trị 10 Mô tả Ngày định xử phạt/Thu phí,lệ phí Số Quyết định xử phạt/Thông báo Thời gian vi phạm Địa điểm vi phạm Tên người vi phạm Tên trường Độ dài tối đa Kiểu liệu TaiKhoanThuNSNN String DSKhoanNop Object Bắt buộc Mô tả trường bắt buộc Không bắt Tài khoản đơn vị buộc định/thông báo mở KBNN 255 Bắt buộc Danh sách Nội dung khoản nộp/Mã định danh hồ sơ ✓ Các trường thông tin chi tiết DSKhoanNop: Tên trường Kiểu liệu Độ dài tối đa Bắt buộc NoiDung String 255 Bắt buộc SoTien String 255 Bắt buộc Mô tả Nội dung khoản nộp/Mã định danh hồ sơ Số tiền Thuộc tính đầu Tên trường Kiểu 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 URL để chuyển hướng người dung MaXacThuc String 255 Bắt buộc Chuỗi mã hóa tin 2.3.2 API Lấy biên lai toán URL: Xem bảng Thông tin kết nối Request method: POST Tham số đầu vào đầu đối tượng JSON với thuộc tính đây: Thuộc tính đầu vào Tên trường Kiểu liệu Độ dài tối đa Bắt buộc Mô tả LoaiBanTin String 50 Bắt buộc GET_BILL PhienBan String 50 Bắt buộc 1.0.6 MaDoiTac Number 12 Bắt buộc Mã định danh đối tác 11 MaThamChieu String 255 Bắt buộc Mã giao dịch phía đối tác ThoiGianGD String 50 Bắt buộc Thời gian thực giao dịch yyyyMMddHHmmss MaXacThuc String 255 Bắt buộc Chuỗi mã hóa tin Thuộc tính đầu Kiểu Độ dài 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 toán (*) Tên trường (*) Hướng dẫn tải file biên lai: Khi lấy đường dẫn file biên lai qua API (trường UrlBienLai), BNĐP thay chuỗi “ip-ss-donvi” địa IP SS BNĐP tiến hành tải file 2.3.3 API Nhận kết giao dịch Request method: POST Content-type: application/x-www-form-urlencoded Parameter name: data Bản tin thông báo kết giao dịch có dạng sau: POST /merchant/confirm HTTP/1.1 HOST: example.com Content-type: application/x-www-form-urlencoded Content-length: data={“LoaiBanTin”:”CONFIRM”,“MaLoi”:”00”,….} Tham số đầu vào đầu đối tượng JSON với thuộc tính đây: Thuộc tính đầu vào Tên trường Kiểu liệu Độ dài tối đa Bắt buộc Mô tả LoaiBanTin String 50 Bắt buộc CONFIRM MaLoi String 10 Bắt buộc Kết thực giao dịch 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 12 SoTien Number 12 Bắt buộc Số tiền MaTienTe String 50 Bắt buộc Đơn vị tiền tệ VND USD MaGiaoDich String 255 Bắt buộc Mã giao dịch Payment Platform MaNganHang String 50 Bắt buộc Phương thức 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 toán 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 thẻ NamThe String 50 Bắt buộc Năm hết hạn thẻ MaXacThuc String 255 Bắt buộc Chuỗi mã hóa tin Tên trường Kiểu 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 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 ThoiGianGD String 50 Bắt buộc Thời gian phía đối tác (yyyyMMddHHmmss) MaXacThuc String 255 Bắt buộc Chuỗi mã hóa tin Thuộc tính đầu 2.3.4 Nhận kết toán giao diện (redirect) Sau toán xong, Khách hàng redirect từ trang toán Payment Platform trang returnUrl website BNĐP, returnUrl truyền thêm tham số sau: returnUrl?data=[MaThamChieu]&responseCode=[MaLoi] &secureCode=[MaXacThuc] BNĐP cung cấp returnUrl để Payment Platform cấu hình hệ thống 13 2.3.5 Hướng dẫn tạo chữ ký Chữ ký tính tốn dựa thuật tốn SHA-256, giá trị tính tốn dựa chuỗi gồm trường thông tin tin gửi sang Payment Platform, nguyên tắc tạo chuỗi sau: - Thứ tự trường thứ tự từ xuống bảng mô tả thông tin đầu vào - Các trường phân tách ký tự “|” - Các trường định nghĩa khơng bắt buộc (Optional) giá trị rỗng - Secret key đứng cuối III DỮ LIỆU GIAO DỊCH 3.1 Mô tả Hàng ngày hệ thống Payment Platform sinh file liệu giao dịch (yyyymmdd_ECOM.csv) ngày (ngày T) từ 00:00 đến 23h:59 bao gồm giao dịch thành công lên thư mục SFTP thống 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 liệu: Các trường đặt cách dấu # Kiểu MaThamChieu String Mã giao dịch đối tác MaGiaoDich String Mã giao dịch phía Payment Platform String Thời gian giao dịch String Trạng thái giao dịch ThoiGianGD TrangThai IV Mô tả Tham số BẢNG MÃ LỖI 4.1.1 Bảng mã lỗi BNĐP trả cho Payment Platform STT Mã lỗi Mô tả lỗi API Nhận kết giao dịch 00 Thành cơng 14 01 Khơng tìm thấy giao dịch 02 Giao dịch xác nhận trước 08 Hệ thống bận timeout 97 Mã xác thực không hợp lệ 99 Các lỗi khác 4.1.2 Bảng mã lỗi Payment Platform trả cho BNĐP STT Mã lỗi Mô tả lỗi 00 Thành công 01 Giao dịch thất bại 02 Dữ liệu không định dạng 03 Mã giao dịch tồn 04 Timeout 05 Khơng tìm thấy liệu 06 Lỗi hệ thống 07 Mã xác thực không 08 Tài khoản đối tác bị khóa 10 09 Tài khoản đối tác khơng tồn 11 96 Hệ thống bảo trì 12 99 Lỗi không xác định 15