TÀI LIỆU HƯỚNG DẪN KẾT NỐI, TÍCH HỢP, CHIA SẺ DỮ LIỆUVỚI CỔNG DỊCH VỤ CÔNG QUỐC GIA

VĂN PHỊNG CHÍNH PHỦ TÀI LIỆU HƯỚNG DẪN KẾT NỐI, TÍCH HỢP, CHIA SẺ DỮ LIỆU VỚI CỔNG DỊCH VỤ CƠNG QUỐC GIA MỤC LỤC I Thơng tin chung Nhiệm vụ, công việc bộ, ngành, địa phương Đầu mối kết nối II Hướng dẫn kỹ thuật .6 Mơ hình tích hợp chia sẻ liệu Các dịch vụ chia sẻ, tích hợp 2.1 Các dịch vụ chia sẻ 2.2 Các dịch vụ tích hợp 12 Yêu cầu chi tiết liệu chia sẻ, tích hợp 14 3.1 Dịch vụ chia sẻ 16 3.2 Dịch vụ tích hợp 39 Hướng dẫn chi tiết việc hiệu chỉnh Cổng DVC, Hệ thống thông tin cửa điện tử BNĐP để kết nối, tích hợp, chia sẻ với Cổng DVC Quốc gia 65 4.1 Các công việc cần thực 65 4.2 Hiệu chỉnh hệ thống DVC .66 4.3 Cung cấp thông tin 67 PHỤ LỤC 70 PHỤ LỤC 71 PHỤ LỤC 82 DANH MỤC CÁC TỪ VIẾT TẮT ST T VIẾT TẮT Ý NGHĨA ADAPTER_URL Địa adapter tích hợp API Giao diện lập trình ứng dụng BNĐP Bộ, ngành, địa phương CSDL Cơ sở liệu Code Kiểu liệu quy định giá trị cần phải lấy từ danh mục quy định từ trước DVC Dịch vụ công DVCQG Dịch vụ công quốc gia IP-PORTSERVER Thông tin IP cổng server deploy API cung cấp sau PAKN Phản ánh, kiến nghị 10 TTHC Thủ tục hành 11 = Ký tự ‘=’ thay cho kí tự ‘ :’ chuối JSON để thể trực quan dễ hiểu Chú ý lập trình sử dụng ký tự ‘ :’ 12 VDXP Nền tảng tích hợp, chia sẻ liệu (Vietnam Data Exchange Platform) I Thông tin chung Nhiệm vụ, công việc bộ, ngành, địa phương a) Thiết lập, hồn thiện Cổng Dịch vụ cơng, Hệ thống thông tin cửa điện tử thống nhất, tập trung để tiếp nhận, giải thủ tục hành chính, cung cấp dịch vụ công trực tuyến thuộc thẩm quyền giải Bộ, ngành, địa phương (gồm quan, đơn vị trực thuộc) Cổng dịch vụ công, Hệ thống thông tin cửa điện tử cấp bộ, cấp tỉnh tuân thủ chức quy định Thông tư 01/2018/TT-VPCP ngày 23/11/2018 Bộ trưởng, Chủ nhiệm Văn phòng Chính phủ hướng dẫn thi hành số quy định Nghị định số 61/2018/NĐ-CP ngày 23/4/2018 Chính phủ thực chế cửa, cửa liên thơng giải thủ tục hành chính, Quyết định số 274/QĐTTg ngày 12/3/2019 Thủ tướng Chính phủ phê duyệt Đề án Cổng dịch vụ công quốc gia: - Danh mục thủ tục hành chính, dịch vụ cơng trực tuyến: đồng với CSDL quốc gia TTHC thông tin khác Tổng hợp số lượng thủ tục hành chính, dịch vụ cơng theo mức độ - Đăng nhập lần từ Cổng Dịch vụ công quốc gia - Xây dựng Bộ câu hỏi – trả lời mẫu - Tiếp nhận phản ánh, kiến nghị người dân, doanh nghiệp giải thủ tục hành kết nối với Hệ thống tiếp nhận, trả lời phản ánh, kiến nghị người dân, doanh nghiệp - Đánh giá việc giải thủ tục hành chính, việc giải phản ánh, kiến nghị quan nhà nước - Tự động sinh mã hồ sơ theo quy định Điều 26 Nghị định số 61/2018/NĐ-CP ngày 23/4/2018 Chính phủ - Cung cấp tình trạng giải thủ tục hành cho Cổng Dịch vụ cơng quốc gia Thời hạn hoàn thành: Quý IV năm 2019 b) Chủ trì, phối hợp với Văn phịng Chính phủ triển khai biện pháp kỹ thuật để kết nối, chia sẻ liệu Cổng thông tin cửa quốc gia, Cổng Dịch vụ công Hệ thống thông tin cửa Bộ, ngành, địa phương với Cổng Dịch vụ công quốc gia Quý III năm 2020 Chuẩn hóa, hồn thiện triển khai tích hợp dịch vụ công trực tuyến mức độ 3, theo danh sách năm 2019 thực hàng năm theo danh mục Thủ tướng Chính phủ phê duyệt Danh sách thủ tục hành ưu tiên kết nối theo Quyết định số 274/QĐ-TTg ngày 12/3/2019 gồm: (1) Tích hợp dịch vụ công trực tuyến mức độ 3, có đối tượng thực hiện, số lượng hồ sơ lớn, liên quan tới cá nhân, tổ chức, gồm: - Dịch vụ công Bảo hiểm xã hội: Đăng ký, điều chỉnh đóng Bảo hiểm xã hội bắt buộc, Bảo hiểm y tế, Bảo hiểm thất nghiệp, Bảo hiểm tai nạn lao động - Bệnh nghề nghiệp; cấp sổ Bảo hiểm xã hội, thẻ Bảo hiểm y tế - Dịch vụ cơng Tài (Lĩnh vực thuế, hải quan): Kê khai hóa đơn qua mạng; Khai thuế qua mạng - Dịch vụ công Kế hoạch đầu tư: Đăng ký doanh nghiệp - Dịch vụ công Giao thơng vận tải: + Nhóm dịch vụ cơng lĩnh vực vận tải đường bộ: nước; quốc tế; + Dịch vụ Đổi Giấy phép lái xe; cấp giấy phép lái xe quốc tế; - Dịch vụ công Y tế: + Nhóm dịch vụ An tồn thực phẩm; + Nhóm dịch vụ Quản lý trang thiết bị y tế - Dịch vụ cơng Tư pháp: Nhóm dịch vụ công lĩnh vực hộ tịch - Dịch vụ công Cơng Thương: Nhóm dịch vụ cơng cấp giấy chứng nhận xuất xứ hàng hóa; dịch vụ xác nhận khai báo hóa chất nhập - Dịch vụ cơng Tài nguyên môi trường: Đăng ký biến động quyền sử dụng đất quyền sở hữu tài sản gắn liền với đất - Nhóm dịch vụ cơng số tổ chức cung ứng dịch vụ công cung cấp: cấp điện; cấp nước (2) Lựa chọn Bộ, ngành, địa phương số tổ chức cung ứng dịch vụ cơng thực tích hợp cung cấp dịch vụ cơng trực tuyến Cổng dịch vụ công quốc gia theo nội dung Đề án, gồm: - Tất Bộ, quan ngang Bộ - 03 quan: Bảo hiểm xã hội Việt Nam, Ngân hàng Chính sách xã hội, Ngân hàng Phát triển Việt Nam - 03 tỉnh, thành phố trực thuộc Trung ương: Hà Nội, Quảng Ninh, Thành phố Hồ Chí Minh năm 2019 triển khai tồn quốc năm 2020 - Các cơng ty, Tổng cơng ty: Tập Đồn điện lực Việt Nam; Cơng ty nước Hà Nội; Tổng công ty cấp nước Sài Gịn c) Hiệu chỉnh Cổng dịch vụ cơng, Hệ thống thông tin cửa điện tử cấp bộ, cấp tỉnh để sử dụng chung Hệ thống xác thực Cổng Dịch vụ công quốc gia Thời hạn hoàn thành: Quý II năm 2020 Hạn chế thiết lập tính năng, hệ thống xác thực với Cổng dịch vụ công, Hệ thống thông tin cửa cấp Bộ, cấp tỉnh, trừ trường hợp kết nối với Hệ thống xác thực Cổng dịch vụ công quốc gia d) Xây dựng Bộ câu hỏi/trả lời vấn đề thường gặp trình giải thủ tục hành cơng khai Cổng Dịch vụ cơng Bộ, ngành, địa phương tích hợp Cổng Dịch vụ công quốc gia Quý IV năm 2019 Bộ câu hỏi/trả lời Bộ, ngành gồm tối thiểu 500 câu hỏi/trả lời đ) Tiếp nhận trả lời ý kiến Hệ thống thông tin tiếp nhận, xử lý phản ánh, kiến nghị cá nhân, tổ chức đăng tải công khai Cổng Dịch vụ công quốc gia Đầu mối kết nối Đầu mối hỗ trợ kết nối Cổng Dịch vụ cơng quốc gia: - Văn phịng Chính phủ: đ/c Nguyễn Đình Lợi, chun viên Cục Kiểm sốt thủ tục hành chính; email: nguyendinhloi@chinhphu.vn; điện thoại: 0984688909 - Tập đồn Bưu – Viễn thơng Việt Nam (VNPT): + Ơng Tào Vũ Hồng, Tổng cơng ty VNPT-IT, email: taovuhoang@vnpt.vn; điện thoại: 0911548444 + Ơng Nguyễn Tiến Nhâm, Tổng cơng ty VNPT-IT, email: ntnham@vnpt.vn; điện thoại: 0948204812 Đầu mối hỗ trợ kết nối với Nền tảng tích hợp chia sẻ liệu (VDXP): - Văn phịng Chính phủ: đ/c Lê Sơn Tùng, chun viên Cục Kiểm sốt thủ tục hành chính; email: lesontung@chinhphu.vn; điện thoại: 0988757775 - Tập đồn Bưu – Viễn thơng Việt Nam (VNPT): + Ơng Lê Văn Đại, Tổng công ty VNPT-IT, email: dailv@vnpt.vn; điện thoại: 0912864248 II Hướng dẫn kỹ thuật Mơ hình tích hợp chia sẻ liệu Hình 1: Mơ hình tích hợp, chia sẻ liệu Để kết nối, chia sẻ, tích hợp liệu Cổng dịch vụ công, Hệ thống thông tin cửa điện tử cấp bộ, cấp tỉnh 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, bộ, ngành, địa phương cần thực nội dung kỹ thuật bao gồm: - Nâng cấp, hoàn thiện chức Cổng dịch vụ cơng quốc gia, HTTT cửa điện tử gồm: danh mục dịch vụ công, xác thực, hồ sơ dịch vụ công, tra cứu, đánh giá kết giải thủ tục hành chính, phản ánh, kiến nghị, toán điện tử - Thiết lập, cài đặt máy chủ bảo mật kết nối (khuyến nghị sử dụng máy chủ bảo mật kết nối hệ thống gửi/nhận văn điện tử giai đoạn đầu) để 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ủ - Phát triển Bộ chuyển đổi (Adapter Server - AS) dịch vụ chia sẻ, tích hợp với Cổng Dịch vụ cơng quốc gia theo thư viện lập trình mẫu hướng dẫn Văn phịng Chính phủ Tn thủ kỹ thuật định dạng liệu gói tin để phục vụ kết nối, tích hợp, chia sẻ thơng tin lẫn với Cổng DVC Quốc gia Mơ hình, hướng dẫn kỹ thuật việc kết nối qua Nền tảng tích hợp, chia sẻ liệu quốc gia VDXP tài liệu kèm theo Trong giai đoạn thử nghiệm, việc kết nối, tích hợp, chia sẻ liệu thực môi trường Internet, thông tin kết nối chi tiết mục II.3 Tài liệu đưa API, BNĐP cần cung cấp theo chuẩn để tích hợp, chia sẻ với Cổng Dịch vụ công quốc gia Các dịch vụ chia sẻ, tích hợp Cổng DVC BNĐP cần bảo đảm định dạng liệu gói tin để phục vụ kết nối, tích hợp, chia sẻ thơng tin với Cổng DVC Quốc gia Các gói tin chia sẻ, tích hợp biểu diễn theo cấu trúc, định dạng dựa JSON Hình 2: Các dịch vụ chia sẻ, tích hợp liệu với Cổng DVC Quốc gia 3.1 Các dịch vụ chia sẻ Cổng DVC Quốc gia cung cấp nhóm dịch vụ chia sẻ gồm: loại liệu dùng chung, dịch vụ xác thực, đăng nhập lần, dịch vụ toán, giao nhận nhà, … cho hệ thống BNĐP sử dụng, đồng thời cung cấp liệu đầu vào cho cổng DVC BNĐP ứng với dịch vụ hỏi đáp, góp ý, phản ánh… công dân, doanh nghiệp STT 1.1 2.1 2.2 Dịch vụ API Mô tả Dịch vụ xác thực, SSO Dịch vụ xác thực qua hệ thống VNConnect (chi tiết Phụ lục 2) Dịch vụ chia sẻ danh mục dùng chung Danh mục tỉnh, GetDanhMucTinhThanh Gói tin cung cấp phương thức lấy thành phố danh sách Tỉnh, Thành phố Danh mục GetDanhMucQuanHuyen Gói tin cung cấp phương thức lấy 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 2.11 2.12 2.13 2.14 quận, huyện Danh mục phường, xã Danh mục quan Danh mục lĩnh vực thủ tục hành Danh mục ngành Danh mục Quốc gia/Quốc tịch Danh mục Dân tộc Danh mục Giới tính Danh mục Nhóm máu Danh mục Tình trạng nhân Danh mục Tơn giáo Danh mục cấp thực thủ tục hành Danh mục kênh 2.15 Danh mục thành phần hồ sơ 2.16 Danh mục phí, lệ phí 2.17 Danh mục thời gian giải 2.18 Danh mục đối tượng tham gia GetDanhMucPhuongXa GetDanhCoQuan GetDanhMucLinhVuc GetDanhMucNganh danh sách Quận, huyện Gói tin cung cấp phương thức lấy danh sách Phường, xã Gói tin cung cấp phương thức lấy danh sách quan tham gia xử lý thủ tục hành Gói tin cung cấp phương thức lấy danh sách lĩnh vực Gói tin cung cấp phương thức lấy danh sách ngành GetDanhMucQuocGia Gói tin cung cấp phương thức lấy danh sách Quốc gia/Quốc tịch GetDanhMucDanToc Gói tin cung cấp phương thức lấy danh sách danh tộc GetDanhMucGioiTinh Gói tin cung cấp phương thức lấy danh sách giới tính GetDanhMucNhomMau Gói tin cung cấp phương thức lấy danh sách nhóm máu GetDanhMucTinhTrangHonN Gói tin cung cấp phương thức lấy han danh sách tình trạng nhân GetDanhMucTonGiao Gói tin cung cấp phương thức lấy danh sách Tơn giáo GetDanhMucCapThucHien Gói tin cung cấp phương thức lấy danh sách cấp thực thủ tục hành GetDanhMucKenh Gói tin cung cấp phương thức lấy danh sách kênh thực thủ tục hành GetDanhMucThanhPhanHoSo Gói tin cung cấp phương thức lấy danh sách thành phần hồ sơ dùng giải thủ tục hành GetDanhMucLePhi Gói tin cung cấp phương thức lấy danh sách phí, lệ phí thực thủ tục hành GetDanhMucThoiHanGiaiQuy Gói tin cung cấp phương thức lấy et danh sách thời gian giải thủ tục hành GetDanhMucDoiTuong Gói tin cung cấp phương thức lấy danh sách đối tượng tham gia vào thủ tục hành - Đường dẫn: https://IP-PORT-SERVER/oauth2/oidcdiscovery/.well-known/openidconfiguration Method: GET 3.9 Kiểm tra phiên - Đường dẫn: https://IP-PORT-SERVER/oidc/checksession Method: GET Input: Request Params o Client_id: client id ứng dụng Tích hợp SSO Hướng dẫn theo luồng grant type: authorization code 4.1 Tạo URL callback DVC BN/ĐP (Service Provider) - Nhiệm vụ: Lấy authorization code sau người dùng đăng nhập chia sẻ thuộc tính thành cơng hình consent Đường dẫn: callback url Method: GET Header: Input: Request Params o code : Mã authorization code VD: https://IP-PORT-SERVER/redirect? code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&state=xcoiv98y2kd22vusuye3kch 4.2 Đăng ký dịch vụ SSO VnConnect - Khai báo cấu hình SSO cho SP VnConnect (bao gồm url callback tạo trên) Lấy thông tin client ID secret ID 4.3 Xây dựng API xác thực tới VnConnect - Đường dẫn: https://IP-PORT-SERVER/oauth2/authorize Method: GET Input: Request Param o response_type=code : (Required) Mô tả loại ủy quyền authorization code Hoặc token implicit o client_id : (Required) định danh cho ứng dụng o redirect_uri : (Required) url callback sau người dùng chấp nhận ủy quyền thành công o scope : (Required) Danh sách quyền mà ứng dụng yêu cầu Bắt buộc phải có openid o state : (optional) ứng dụng gửi lên mã random Mã gửi lại step url callback để ứng dụng xác nhận server gửi yêu cầu (CSRF attack) o acr_values : Quyền truy cập ( LoA1 > LoA4 ) VD: https://IP-PORT-SERVER/oauth2/authorize ?response_type=code &client_id=29352915982374239857 &redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback &scope=openid &acr_values=LoA1  Chú ý: Nếu muốn thêm nhiều scope scope cách dấu + VD: scope=openid+email+… 4.4 Lấy token truy nhập (Get access token) -     Sau đăng nhập đồng ý chấp nhận chia sẻ thuộc tính thành cơng VnConnect gọi lại url callback SP để trả lại authorization code - SP sử dụng authorization code để call API lấy access token: Đường dẫn: https://IP-PORT-SERVER/oauth2/token Method: POST Header: o Content-Type: application/x-www-form-urlencoded Input: Query Params o grant_type=authorization_code o code : Mã authorization code o redirect_uri : o client_id: client id ứng dụng o client_secret : key bí mật ứng dụng Giá trị gửi lên để server xác thực có xác ứng dụng hay khơng hay Phịng tránh kẻ cơng có authorization code bước trước  Output: HTTP/1.1 200 OK { "access_token": "11e6bccd-e16a-35a6-98d2-c7fe594e0045", "refresh_token": "0d41ffa7-f942-38fa-94cf-25a2cc60cd5e", "scope": "openid", "id_token": "eyJ4NXQiOiJOVGhsWm1GaE4yTmpZamt4TmpoalpEVmxOekZsTURReE9UZGpZelUzTk RVM05UaGpNelF6WkEiLCJraWQiOiJOVGhsWm1GaE4yTmpZamt4TmpoalpEVmxOekZs TURReE9UZGpZelUzTkRVM05UaGpNelF6WkEiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoI joiVkVVVlZaTjh1TURsby1nWmVuMlJIdyIsImF1ZCI6Inp1SDlqRXJtZVZmajlxS0p1cmhW MV9XUmg4Y2EiLCJzdWIiOiJhZG1pbiIsIm5iZiI6MTU2MjkyMjg4NywiYXpwIjoienVIOW pFcm1lVmZqOXFLSnVyaFYxX1dSaDhjYSIsImFtciI6WyJwYXNzd29yZCJdLCJpc3MiOiJo dHRwczpcL1wvbWNhLnZucHQtY2Eudm46OTQ0M1wvb2F1dGgyXC90b2tlbiIsImV4cCI6 MTU2MjkyNjQ4NywiaWF0IjoxNTYyOTIyODg3fQ.HvoJ5OzOy4FnEkqY2YSjr5trG19UYz 2D8izHuvSu5l0ywiQOEuVjZU3fxF9m4QcIMArRLyGO97JWAyZIBiuL1uwJNvqLdqbh8PCuSrPIErfy19oXzNpStSMgIzEi4ky1VRodt_KmjnUIA0cBzrE1IQycy8H9fNnUzUjG3qzxg", "token_type": "Bearer", "expires_in": 3600 } 4.5 Lấy thơng tin người dùng Có accsess token ti a hành call api Get userinfo - Đường dẫn: https://IP-PORT-SERVER/oauth2/userinfo - Method: POST - Header: o Accept: application/json o Content-Type: application/x-www-form-urlencoded o Authentication: Bearer - Input: Request Params o scope : (required) Danh sách quyền mà ứng dụng yêu cầu - Output: thông tin người dùng STT Tên Trường Định dạng Mô tả Yêu cầu LoaiTaiKhoan String CD-MaSoThue SoCMND String String SoDinhDanh String LoaiThe String 10 11 12 MaBHXH HoChieu HoVaTen ThuDienTu SoDienThoai SoDienThoaiBan GioiTinh String String String String String String Integer 13 DanToc String 14 TonGiao String Tài khoản dành cho công dân, doanh nghiệp, tổ chức: - 1: Cá nhân - 2: Doanh nghiệp - 3: Tổ chức - 4: Cơ quan nhà nước Mã số thuế Chứng minh thư cước công dân Số Định danh cá nhân Theo quy định QCVN 109:2017/BTTTT Phân biệt thẻ cước CMT Mã bảo hiểm xã hội Thông tin hộ chiếu Thông tin họ, chữ đệm tên Thông tin email Số điện thoại di động Số điện thoại bàn Thơng tin giới tính: chưa có thơng tin Nam Nữ Thơng tin dân tộc: 00 chưa có thơng tin Xx hai ký tự số thể mã dân tộc quy định Quyết định số 1019/QĐ-TCTK ngày 12 tháng 11 năm 2008 Tổng cục Thống kê (đã cập nhật bổ sung) Thơng tin tơn giáo: 00 chưa có thông tin 99 không theo tôn giáo Xx hai ký tự số thể mã tôn giáo quy định Quyết định số 1019/QĐ-TCTK ngày 12 tháng 11 năm 2008 15 TinhTrangHonNhan Integer 16 NhomMau String 17 18 NgayThangNamSinh NoiDangKyKhaiSin h QueQuan ThuongTru NoiOHienNay QuocTich Cha Me VoChong NguoiDaiDien ChuHo TrangThai Date String 19 20 21 22 23 24 25 26 27 28 29 ST T Tổng cục Thống kê (đã cập nhật bổ sung) Tình trạng nhân: chưa có thơng tin chưa kết có vợ/chồng ly góa vợ/chồng 00 chưa có thơng tin 01 nhóm máu A 02 nhóm máu B 03 nhóm máu AB 04 nhóm máu Thông tin ngày, tháng, năm sinh Thông tin nơi đăng ký khai sinh Thông tin quê quán Thông tin thường trú Nơi Thông tin quốc tịch Thông tin tên cha Thông tin tên mẹ Thông tin vợ chồng Thông tin người đại diện Thông tin chủ hộ Thông tin trạng sống hay chết hay tích CD-TechID String Technical ID cơng dân hệ thống VNConnect Bảng : Các trường kết lấy thông tin người dùng công dân Tên Trường DN-MaSoThue MaSoDoanhNghie p TenDoanhNghiep DiaChi SoDienThoai String String String Integer String String String String String String Định dạng String String Mô tả Mã số thuế doanh nghiệp Mã số doanh nghiệp String String String Tên doanh nghiệp Địa doanh nghiệp Số điện thoại doanh nghiệp Yêu cầu ThuDienTu DN-TechID String String Email doanh nghiệp Technical Id Mã số kỹ thuật doanh nghiệp hệ thống VNConnect Bảng : Các trường kết lấy thông tin người dùng doanh nghiệp 4.6 Revoke token - Người dùng logout khỏi ứng dụng SP sử dụng API revoke token để thu hồi lại access token cấp cho SP trước đó: Đường dẫn: https://IP-PORT-SERVER/oauth2/revoke Method: POST Header: o Content-Type: application/x-www-form-urlencoded Input: Query Params o token: token muốn hủy o token_type_hint = access_token o client_id: client id ứng dụng o client_secret : key bí mật ứng dụng PHỤ LỤC HƯỚNG DẪN TÍCH HỢP HỆ THỐNG THANH TOÁN TRỰC TUYẾN VÀ CÁC API SỬ DỤNG Thơng tin tích hợp API_BASE_URL MERCHANT_SERVICE_ ID SECRET KEY API_KEY Cung cấp tích hợp Cung cấp tích hợp Cung cấp tích hợp Cung cấp tích hợp Quy trình giao dịch  Khách hàng truy cập website cung cấp dịch vụ để sử dụng dịch vụ chọn Thanh tốn  Cổng dịch vụ cơng, HTTT cửa điện tử, nhà cung cấp dịch vụ khác (điện, nước,…) gửi yêu cầu khởi tạo toán sang Payment Connect thông qua API  Payment Connect trả URL để website chuyển hướng khách hàng tới Payment Connect để tiếp tục toán  Khách hàng chọn ngân hàng để toán tiến hành xác thực thông tin tài khoản ngân hàng  Sau tốn xong, Payment Connect thơng báo kết giao dịch cho Website qua API, sau chuyển hướng khách hàng Website để thông báo kết giao dịch Hướng dẫn tích hợp Các API cung cấp dạng RESTful, thực truy cập vào API đối tác cần thiết lập header Authorization với giá trị Bearer API_KEY cấp đăng ký tài khoản đối tác Hệ thống cung cấp API sau: - API khởi tạo dịch API toán sử dụng Token Đối tác cần cung cấp API return_url để nhận kết giao dịch từ Payment Connect: - API xác nhận giao dịch (confirm) Return URL để redirect KH sau toán xong 3.1 API Khởi tạo giao dịch URL: {api_base_url}/init Request method: POST Tham số đầu vào đầu object JSON với thuộc tính đây: Thuộc tính đầu vào Mandatory Name Type Length Comments /optional ACTION String 1,50 M INIT VERSION String 1,50 M 1.0.6 1,12 M Mã định danh đối tác 1,255 M Mã giao dịch phía đối tác 1,50 M Số tiền toán MERCHANT_SERVICE Number _ID MERCHANT_ORDER String _ID String AMOUNT PAYMENT_ACTION CHANNEL_ID String 1,50 M String 0,255 M PAY: Thanh tốn thơng thường khơng trả Token CREATE_TOKEN: Tạo Token TOKEN: Thanh tốn có trả Token Kênh toán 1: WebApp - 2: MobileApp Number 0,12 M Mã thiết bị, mặc định truyền String 1,10 M Ngôn ngữ: vi-VN/en-US; mặc định vi-VN CURRENCY_CODE String 1,50 M Đơn vị tiền tệ VND USD PAYMENT_METHO D DESCRIPTION String 1,50 M Phương thức toán String 1,255 M Mô tả giao dịch String 1,255 M Phương thức xác thực: ATM/tài khoản/CIF ADDITIONAL_INFO String 1,4000 M Thông tin thêm CUSTOMER_INFO String 1,4000 M Thông tin KH DEVICE LOCALE AUTHEN_TYPE Thời gian giao dịch, định dạng CREATE_DATE String 1,50 M yyyyMMddHHmmss CLIENT_IP String 1,50 M IP khách hàng SECURE_CODE String 1,255 M Chuỗi mã hóa tin Thuộc tính đầu Name Type Length Mandatory /optional Comments RESPONSE_CODE String 1,10 M Mã lỗi DESCRIPTION String 1,255 M Mô tả lỗi REDIRECT_URL String 1,255 M SECURE_CODE String 1,255 M URL để chuyển hướng khách hàng Chuỗi mã hóa tin Các thơng tin chi tiết trường ADDITIONAL_INFO: Tham số Kiểu Mô tả Required TenNguoiNop String Họ tên người nộp Required TKThuHuong String Tài khoản ngân hàng thụ Required hưởng MaNHThuHuong String Mã ngân hàng thụ hưởng TenTKThuHuong String MSTNguoiNop String DiaChiNguoiNop String Tên chủ tài khoản ngân hàng thụ hưởng Mã số thuế người nộp Địa người nộp bao gồm Required Required Required Required tỉnh/thành phố, quận huyện, làng xã đường đặt cách “|” DiaChiNguoiNopThay String TenNguoiNopThay String Địa người nộp bao gồm tỉnh/thành phố, quận huyện, làng xã đường đặt cách “|” Họ tên người nộp thay Required Required Tên Kho bạc Nhà nước nơi Required nhận khoản thu ngân sách nhà nước Tài khoản Kho Required bạc Nhà nước TenKBNN String TaiKhoanKBNN String TenNHHuongKBNN String Tên ngân hàng hưởng KBNN Required LoaiTKNopNSNN String Loại tài khoản nộp ngân sách nhà nước Required TenCoQuanYeuCauNop String Tên qauan quản lý thu Required ThongTinLienQuan String Các thông tin liên quan Required MaGDKhoanNopNSNN String Mã giao dịch khoản nộp ngân sách nhà nước Optional MaHoSo String Mã hồ sơ Required LoaiPhiTTHC String Loại phí thủ tục hành Required Các thơng tin chi tiết trường CUSTOMER_INFO Name Type Length Mandatory /optional Comments CUSTOMER_ID String 1,255 M Số CMND/Hộ chiếu CUSTOMER_NAME String 1,255 M Họ tên KH CUSTOMER_DOB String 1,255 M Ngày sinh KH CUSTOMER_ACCOUN T_NO CUSTOMER_CARD_ NO CUSTOMER_CARD_D ATE CUSTOMER_MOBIL E String 1,255 M Số TK khách hàng String 1,255 M Số thẻ ATM KH String 1,255 M Ngày hết hạn thẻ String 1,255 M SĐT đăng ký SMS ngân hàng 3.2 API Thanh toán sử dụng Token URL: {api_base_url}/init_with_token Request method: POST Tham số đầu vào đầu object JSON với thuộc tính đây: Thuộc tính đầu vào Name Type Length Mandatory /optional Comments ACTION String 1,50 M INIT_WITH_TOKEN VERSION String 1,50 M 1.0.6 MERCHANT_SERVICE_ID Number 1,12 M Mã định danh đối tác MERCHANT_ORDER_ID String 1,255 M Mã giao dịch phía đối tác AMOUNT String 1,50 M Số tiền toán CURRENCY_CODE String 1,50 M Đơn vị tiền tệ VND USD PAYMENT_METHOD String 1,50 M Phương thức tốn DESCRIPTION String 1,255 M Mơ tả giao dịch TOKEN String 1,50 M Token toán Khách hàng CARD_EXPIRY_MON TH CARD_EXPIRY_YEA R String 1,50 M Thangs hết hạn thẻ, VD: 07 String 1,50 M Năm hết hạn thẻ, VD: 18 Thời gian giao dịch, định dạng CREATE_DATE String 1,50 M yyyyMMddHHmmss SECURE_CODE String 1,255 M Chuỗi mã hóa tin Thuộc tính đầu Name Type Length Mandatory /optional Comments RESPONSE_CODE String 1,10 M Mã lỗi DESCRIPTION String 1,255 M Mô tả lỗi REDIRECT_URL String 1,255 M SECURE_CODE String 1,255 M URL để chuyển hướng khách hàng Chuỗi mã hóa tin 3.3 API Confirm giao dịch Đối tác cung cấp cho Payment Connect Request method: POST Content-type: application/x-www-form-urlencoded Parameter name: data Bản tin confirm có dạng sau: POST /merchant/confirm HTTP/1.1 HOST: example.com Content-type: application/x-www-form-urlencoded Content-length: data={“ACTION”:”CONFIRM”,“RESPONSE_CODE”:”00”,….} Tham số đầu vào đầu object JSON với thuộc tính đây: Thuộc tính đầu vào Mandator Name Type Length y Comments /optional String 1,50 M CONFIRM ACTION RESPONSE_CODE String 1,10 M Kết thực giao dịch MERCHANT_SERVICE_I D MERCHANT_ORDER_ID Number 1,12 M Mã định danh đối tác String 1,255 M Mã giao dịch phía đối tác AMOUNT Number 1,8 M Số tiền CURRENCY_CODE String 1,50 M Đơn vị tiền tệ VND USD TRANSACTION_ID String 1,255 M PAYMENT_METHOD String 1,50 M Mã giao dịch Payment Connect Phương thức toán Ngày giao dịch, định dạng PAY_DATE String 1,50 M (yyyyMMddHHmmss) ADDITIONAL_INFO String 1,255 M Thông tin mô tả đơn hàng TOKEN String 1,255 M Token ACCOUNT_ID String 1,255 M Số thẻ CARD_EXPIRY_MONTH String 1,50 M Tháng hết hạn thẻ CARD_EXPIRY_YEAR String 1,50 M Năm hết hạn thẻ SECURE_CODE String 1,255 M Chuỗi mã hóa tin Thuộc tính đầu Name Type Length Mandatory /optional Comments RESPONSE_CODE String 1,10 M Mã lỗi DESCRIPTION String 1,255 M Mô tả lỗi MERCHANT_SERVICE_ID Number 1,12 M Mã định danh đối tác MERCHANT_ORDER_ID String 1,255 M Mã giao dịch phía đối 90 tác String CREATE_DATE 1,50 M Thời gian phía đối tác String SECURE_CODE 1,255 M (yyyyMMddHHmmss) Chuỗi mã hóa tin 3.4 Bảng mã lỗi đối tác trả cho Payment Connect No RESPONSE_CODE DESCRIPTION ACTION = CONFIRM 00 Thành cơng 01 Khơng tìm thấy giao dịch 02 Giao dịch confirm 08 97 Hệ thống bận timeout Chữ ký không hợp lệ 99 Các lỗi khác 3.5 Bảng mã lỗi cho Payment Connect trả cho đối tác No RESPONSE_CODE DESCRIPTION 00 Thành công 01 Giao dịch thất bại 02 03 Dữ liệu không định dạng Mã giao dịch tồn 04 Timeout 05 Khơng tìm thấy liệu 06 Lỗi hệ thống 07 08 10 09 11 96 Chữ ký không Tài khoản đối tác bị khóa Tài khoản đối tác khơng tồn Hệ thống bảo trì 91 12 99 Lỗi khơng xác định Hướng dẫn tạo secure code Secure code tính toán dựa thuật toá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 Connect, 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 92 ... để tích hợp, chia sẻ với Cổng Dịch vụ cơng quốc gia Các dịch vụ chia sẻ, tích hợp Cổng DVC BNĐP cần bảo đảm định dạng liệu gói tin để phục vụ kết nối, tích hợp, chia sẻ thông tin với Cổng DVC Quốc. .. dailv@vnpt.vn; điện thoại: 0912864248 II Hướng dẫn kỹ thuật Mơ hình tích hợp chia sẻ liệu Hình 1: Mơ hình tích hợp, chia sẻ liệu Để kết nối, chia sẻ, tích hợp liệu Cổng dịch vụ công, Hệ thống thông tin cửa... tảng tích hợp, chia sẻ liệu quốc gia VDXP tài liệu kèm theo Trong giai đoạn thử nghiệm, việc kết nối, tích hợp, chia sẻ liệu thực môi trường Internet, thông tin kết nối chi tiết mục II.3 Tài liệu