Nền tảng tích hợp, chia sẻ liên thông kết nối chính quyền điện tử thành phố

Giải pháp thực hiện

TỔNG QUAN
1. Mục đích tài liệu

Tài liệu này hướng dẫn các đơn vị của BNĐP kết nối tới hệ thống NGSP thông qua Nền tảng HCM LGSP để thực hiện thanh toán DVC trực tuyến toàn quốc.
1. Phạm vi và đối tượng áp dụng
Tài liệu này cung cấp các phương thức, đối tượng cho lập trình viên sử dụng để phát triển tích hợp ứng dụng đơn vị của BNĐP với các dịch vụ hổ trợ thanh toán DVC trực tuyến toàn quốc thông qua Nền tảng HCM LGSP.
1. Thông tin kết nối
Đơn vị cần kết nối liên hệ sở Thông tin và Truyền thông để được cung cấp thông tin kết nối bao gồm:
- AppName
- AccessKey
- SecretKey
- PartnerCode
- PartnerCodeCus

MÔ HÌNH KẾT NỐI
1. Mô hình kết nối

Hình 1: Mô hình kết nối

Nền tảng NGSP thực hiện chia sẻ dịch vụ hỗ trợ thanh toán DVC trực tuyến cho Nền tảng LGSP
Nền tảng LGSP đảm nhiệm vai trò chính trong việc kết nối với Nền tảng NGSP để thực hiện việc hổ trợ thanh toán DVC cho đơn vị
API thanh toán trực tuyến hỗ trợ phần mềm tại đơn vị kết nối vào Nền tảng LGSP để thực hiện thanh toán trực tuyến
1. Quá trình trao đổi gói tin

Hình 2: Quy trình trao đổi gói tin

Bước 1: Phần mềm của đơn vị gọi đến Nền tảng LGSP thông qua api kèm theo access token.
Bước 2: Nền tảng LGSP kiểm tra access token của đơn vị. Nếu thất bại sẽ trả về mã lỗi được mô tả như bên dưới

Mã lỗi <Error_Number>	Ý nghĩa
401	Sai thông tin xác thực
403	Tài khoản không có quyền truy cập API
429	Vượt quá số lượng request cho phép trong một đơn vị thời gian

Bước 3: Nền tảng LGSP xử lý dữ liệu và trả về gói tin JSON kết quả cho phần mềm đơn vị.

ĐẶC TẢ API
1. Thông tin kết nối

Kiểu	Diễn giải	Ví dụ
Địa chỉ adapter Nền tảng HCM thử nghiệm	Địa chỉ cổng dịch vụ chính thức	https://hcmesb-test.tphcm.gov.vn
Địa chỉ adapter Nền tảng HCM chính	Địa chỉ cổng dịch vụ thử nghiệm	https://hcmlgsp.tphcm.gov.vn
AccessKey	Khóa	rTkhYCBwHM
SecretKey	Khóa bí mật	DWkQgY1YSS
AppName	Đơn vị kết nối	TPHCM
PartnerCode	Mã đơn vị cung cấp ứng dụng	000.00.01.H29
PartnerCodeCus	Mã đơn vị sử dụng dịch vụ	000.00.01.H29
lgspaccesstoken	Khai báo trong Header, Là chuỗi gồm 5 tham số dạng json được mã hóa thành StringBase64	ewoiQWNjZXNzS2V5IjoiclRraFlDQndITSIsCiJTZWNyZXRLZXkiOiJEV2tRZ 1kxWVNTIiwKIkFwcE5hbWUiOiAiVFBIQ00iLAoiUGFydG5lckNvZGUiOiAi MDAwLjAwLjAxLkgyOSIsCiJQYXJ0bmVyQ29kZUN1cyI6ICIwMDAuMD AuMDEuSDI5Igp9Cg== được stringbase64 từ: { "AccessKey":"rTkhYCBwHM", "SecretKey":"DWkQgY1YSS", "AppName": "TPHCM", "PartnerCode": "000.00.01.H29", "PartnerCodeCus": "000.00.01.H29" }

Bảng 1: Bảng thông tin kết nối

1. API yêu cầu thanh toán
Đường dẫn: /paygov/yeuCauThanhToan
Method: POST
Đầu vào:
- Header:
  - Content-Type: application/json
  - lgspaccesstoken: Base64
  - Authorization: Bearer {token}
- Body: dữ liệu truyền vào

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
partnerCode	Alphanumeric	partnerCode của tài khoản đơn vị khai thác	✓	HN_Partner_12
accessKey	Alphanumeric	Chuỗi mã hóa xác định quyền truy cập	✓	f6047c5b34702d1edd05926c421317f62a58edc 3e1c06ce74820da43d4d26ec6,-360862545
returnUrl	Alphanumeric	Địa chỉ trả về khi thực hiện thanh toán xong	✓	http://paygate.com/return
orderId	Alphanumeric	Mã đơn hàng cần thanh toán Quy tắc tạo OrderID: orderId = docCode + "-" + < số lượt thanh toán của hồ sơ > Số lượt thanh toán của hồ sơ tối đa 2 ký tự.	✓	000.06.38.H49-200722-0001-01
amount	Numeric	Tổng số tiền cần thanh toán	✓	10000
orderInfo	Alphanumeric	Thông tin mô tả nội dung thanh toán	✓	Nap 100K cho so dien thoai
requestCode	Alphanumeric	Mã yêu cầu thanh toán	✓	Payment123
ipAddress	Alphanumeric	Địa chỉ ip khách hàng thanh toán	✓	120.72.114.112
serviceCode	Alphanumeric	Mã dịch vụ cần thanh toán	✓	Pay_DVC
checksum	Alphanumeric	Mã đảm bảo toàn vẹn dữ liệu. Dùng giao thức Sha256 để mã hóa các thông tin gồm : secretKey + accessKey +partnerCode + orderId + requestCode + amount	✓	3B2C7C400EB89625A82B9F92B82863F4E997A9D BDEA726AF7FBB4F2DBF6C2ABD

Bảng 2: Bảng dữ liệu truyền vào API yêu cầu thanh toán

Ví dụ:

{

"partnerCode": "PAYGOV-HOCHIMINH",

"accessKey": "22c7b18b020dec7a5b45a25103a5a9b4c52d94d384f6375449e7e026b21e3183",

"amount": 50000,

"orderId": "SBN_100013",

"orderInfo": "Nap 100K cho so dien thoai",

"serviceCode":"dvc_hcm",

"requestCode": "Payment1234",

"returnUrl": "http://pay-test.tphcm.gov.vn/return",

"ipAddress": "118.69.125.122",

"checksum": "7e14f28d76b5e13a5e63b4a5f8839f9eabdf694601887828caa887d793bb689a"

}

Đầu ra:
- Thông tin dữ liệu trả về

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
error_code	Alphanumeric	Mã lỗi thực hiện yêu cầu: SUCCESSFUL: thành công FAILED: thất bại, PARAM_ERROR: Dữ liệu gửi lên thiếu nội dung SIGNTURE_WRONG: Dữ liệu không toàn vẹn AC-COUNT_NOT_EXIST: Tài khoản không tồn tại PART-NER_NOT_EXIST: Đơn vị kết nối không tồn tại ACCESS-INFO_NOT_EXIST: Thông tin truy cập không tồn tại SER-VICE_NOT_EXIST: Dịch vụ không tồn tại ORDER_EXITS: Giao dịch đã tồn tại	✓	SUCCESSFUL
error_message	Alphanumeric	Thông tin error message	✓	Thành công
data	Alphanumeric	Địa chỉ trả về đường dẫn thanh toán	✓	http://103.9.0.215/paygate/return

Bảng 3: Bảng dữ liệu trả về API yêu cầu thanh toán

Ví dụ:

Kết quả thành công

Kết quả thất bại

{

"error_code": "SUCCESSFUL",

"error_message": "",

"data": {

"url": "https://pay.gov.vn/paygate/choose/payment?partnerCode=PAYGOV-HOCHIMINH&accessKey=

22c7b18b020dec7a5b45a25103a5a9b4c52

d94d384f6375449e7e026b21e3183&requestCode=Payment1234

&orderId=SBN_100013&amount=50000&ipAddress=118.69.125.122&

returnUrl=http://pay-test.tphcm.gov.vn/return&orderInfo

=Nap 100K cho so dien thoai&signature=7e14f28d76b5e

13a5e63b4a5f8839f9eabdf694601887828caa887d793bb689a"

}

{

"error_code": "FAILED",

"error_message": "",

"data":

}

1. API yêu cầu truy vấn giao dịch
Đường dẫn: /paygov/yeuCauTruyVanGiaoDich
Method: POST
Đầu vào:
- Header:
  - Content-Type: application/json
  - lgspaccesstoken: Base64
  - Authorization: Bearer {token}
- Body: Request data gửi lên:

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
partnerCode	Alphanumeric	partnerCode của tài khoản website dịch vụ	✓	CTTQG-Partner-12
accessKey	Alphanumeric	Chuỗi mã hóa xác định quyền truy cập	✓	1a2b3c4d5e6f7g8hi9j
requestCode	Alphanumeric	Mã yêu cầu thanh toán	✓	1278547
orderId	Alphanumeric	Mã hóa đơn yêu cầu thanh toán	✓	H1001250
checksum	Alphanumeric	Mã đảm bảo toàn vẹn dữ liệu. Dùng giao thức Sha256 để mã hóa các thông tin gồm : secretKey + partnerCode + accessKey + orderId + requestCode		7afd6ccff4646e6d822c56c7554beb0a57f408e6f9b5c568c3cd44797ab004e

Bảng 4: Bảng dữ liệu truyền vào API yêu cầu truy vấn giao dịch

Ví dụ:

{

"partnerCode": "PAYGOV-HOCHIMINH",

"accessKey": "22c7b18b020dec7a5b45a25103a5a9b4c52d94d384f6375449e7e026b21e3183",

"orderId": "SBN_100012",

"requestCode": "Payment123",

"checksum": "f08b718a59d30deb2e52ecddfd605f8be64db469b6eedadddd09886e6b574c81"

}

Đầu ra:

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
partnerCode	Alphanumeric	partnerCode của tài khoản website dịch vụ	✓	CTTQG-Partner-12
transactionNo	Alphanumeric	Mã giao dịch	✓	Payment123
requestCode	Alphanumeric	Mã yêu cầu thanh toán	✓	1278547
amount	Numeric	Số tiền thanh toán	✓	400000
payCenter	Alphanumeric	Mã cổng nhận hoàn trả	✓	Momo
orderId	Alphanumeric	Mã hóa đơn yêu cầu thanh toán	✓	H1001250
orderPayId	Alphanumeric	Mã hóa đơn chấp nhận thanh toán	✓	H1001250_123
orderInfo	Alphanumeric	Nội dung thanh toán		Nap tien dien thoai
type	Alphanumeric	Loại giao dịch: refund: hoàn trả pay: thanh toán	✓	20190603191334
payDate	Alphanumeric	Thời gian thanh toán	✓	20190603191334
errorCode	Alphanumeric	Trạng thái giao dịch 00 : thành công #00 : thất bại	✓	00
error_code	Alphanumeric	Mã lỗi thực hiện yêu cầu : SUCCESSFUL: thành công FAILED: thất bại, PARAM_ERROR: Dữ liệu gửi lên thiếu nội dung PARTNER_NOT_EXIST: Đơn vị kết nối không tồn tại ACCESSINFO_NOT_EXIST: Thông tin truy cập không tồn tại ORDER_NOT_EXITS: Giao dịch không tồn tại SIGNATURE_WRONG: Dữ liệu không toàn vẹn	✓	SUCCESSFUL
error_message	Alphanumeric	Message thông báo	✓	Thanh cong

Bảng 5: Bảng dữ liệu trả về API yêu cầu truy vấn giao dịch

Ví dụ:

Kết quả thành công

Kết quả thất bại

{

"error_code": "SUCCESSFUL",

"error_message": "",

"data": {

"payCenter": "Napas",

"amount": "40000",

"partnerCode": "PAYGOV-HOCHIMINH",

"orderId": "SBN_100012",

"orderInfo": "Thanh toan dich vu SBN_100012",

"transactionNo": "835678273",

"requestCode": "Payment123",

"errorCode": "00",

"type": "pay",

"orderPayId": "SBN_100012_HCMPay933",

"payDate": "20200804100556"

}

{

"error_code": "FAILED",

"error_message": "",

"data": null

}

1. API hoàn trả giao dịch
Đường dẫn: /paygov/yeuCauHoanTraGiaoDich
Method: POST
Đầu vào:
- Header:
  - Content-Type: application/json
  - lgspaccesstoken: Base64
  - Authorization: Bearer {token}
- Body: Request data gửi lên

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
partnerCode	Alphanumeric	partnerCode của tài khoản website dịch vụ	✓	CTTQG-Partner-12
accessKey	Alphanumeric	Chuỗi mã hóa xác định quyền truy cập	✓	1a2b3c4d5e6f7g8hi9j
transactionNo	Alphanumeric	Mã giao dịch	✓	Payment123
requestCode	Alphanumeric	Mã yêu cầu thanh toán	✓	1278547
amount	Numeric	Số tiền thanh toán	✓	400000
orderId	Alphanumeric	Mã hóa đơn yêu cầu thanh toán	✓	H1001250
orderInfo	Alphanumeric	Nội dung hoàn tiền	✓	Nap tien dien thoai
transactionType	Alphanumeric	Loại hoàn tiền 02 : hoàn tiền toàn phần	✓	02
checksum	Alphanumeric	Mã đảm bảo toàn vẹn dữ liệu. Dùng giao thức Sha256 để mã hóa các thông tin gồm : secretKey + accessKey +partnerCode + orderId + transactionNo + orderInfo + amount + requestCode + transactionType	✓	3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA 726AF7FBB4F2DBF6C2ABD

Bảng 6: Bảng dữ liệu truyền vào API hoàn tr giao dịch

Ví dụ:

{

"partnerCode": "PAYGOV-HOCHIMINH",

"accessKey": "22c7b18b020dec7a5b45a25103a5a9b4c52d94d384f6375449e7e026b21e3183",

"orderId": "SBN_100012",

"transactionNo": "835678273",

"orderInfo": "hoan tra tien dt",

"amount": 400000,

"requestCode": "Payment123",

"transactionType": "02",

"checksum": "52346c9c61c8247aa3d986c6f94a9eb594fb3e0de469cd23d62a18854ea3c99f"

}

Đầu ra:

Tên tham số	Kiểu dữ liệu	Mô tả	Bắt buộc	Ví dụ
error_code	Alphanumeric	Mã lỗi thực hiện yêu cầu: SUCCESSFUL: thành công FAILED: thất bại, PARAM_ERROR: Dữ liệu gửi lên thiếu nội dung PARTNER_NOT_EXIST: Đơn vị kết nối không tồn tại ACCESS-INFO_NOT_EXIST: Thông tin truy cập không tồn tại ORDER_NOT_EXITS: Giao dịch không tồn tại ORDER_EXITS: Giao dịch đã được hoàn trả SIGNATURE_WRONG: Dữ liệu không toàn vẹn	✓	SUCCESSFUL
error_message	Alphanumeric	Thông tin error message	✓	Thành công
transactionNo	Alphanumeric	Mã giao dịch khi hoàn trả	✓	Payment123
requestCode	Alphanumeric	Mã yêu cầu yêu cầu khi hoản trả về	✓	1278547
amount	Numeric	Số tiền hoàn trả	✓	400000
orderId	Alphanumeric	Mã hóa đơn yêu cầu hoàn trả	✓	H1001250
orderPayId	Alphanumeric	Mã hóa đơn chấp nhận hoàn trả thanh toán	✓	H1001250_123
orderInfo	Alphanumeric	Nội dung hoàn trả		Nap tien dien thoai
payDate	Alphanumeric	Thời gian thanh toán	✓	20190603191334
errorCode	Alphanumeric	Trạng thái giao dịch 00 : thành công #00 : thất bại	✓	00
payCenter	Alphanumeric	Mã cổng nhận hoàn trả	✓	Momo
checksum	Alphanumeric	Mã đảm bảo toàn vẹn dữ liệu. Dùng giao thức Sha256 để mã hóa các thông tin gồm : secretKey + requestCode + amount + orderId + orderPayId + orderInfo +transactionNo + payDate + errorCode + payCenter	✓	3B2C7C400EB89625A82B9F92B82863F4E997 A9DBDEA726AF7FBB4F2DBF6C2ABD

Bảng 7: Bảng dữ liệu trả về API hoàn trả giao dịch

Ví dụ:

Kết quả thành công

Kết quả thất bại

{

"error_code": "SUCCESSFUL",

"error_message": "",

"data": {

"payCenter": "Napas",

"amount": 40000,

"orderId": "000.00.00.H29-200804-0002-01",

"orderInfo": "Thanh toan dich vu 000.00.00.H29-200804-0002-01",

"transactionNo": "835678956",

"checksum": "af34fc82526c7ea2e9be6157a39

d8b0e8ae9fe4ec53bb511571e3464b3d840d4",

"requestCode": "Payment2",

"errorCode": "00",

"orderPayId": "000.00.00.H29-200804-0002-01",

"payDate": "20200805111731"

}

{

"error_code": "FAILED",

"error_message": "",

"data": null

}

Danh sách tệp tin đính kèm

HCM_LGSP_He thong ho tro thanh toan DVC truc tuyen _v1.0.docx

Giải pháp thực hiện

Danh sách tệp tin đính kèm

Dịch vụ kết nối Hệ thống hỗ trợ thanh toán dịch vụ công trực tuyến toàn quốc (PayGOV)

Câu hỏi thường gặp

CHÚNG TÔI LUÔN SẴN
SÀNG ĐỂ GIÚP ĐỠ BẠN

Để được hỗ trợ tốt nhất. Hãy gọi

SỞ THÔNG TIN VÀ TRUYỀN THÔNG TPHCM

LIÊN KẾT WEBSITE

KẾT NỐI VỚI CHÚNG TÔI

Giải pháp thực hiện

Danh sách tệp tin đính kèm

Dịch vụ kết nối Hệ thống hỗ trợ thanh toán dịch vụ công trực tuyến toàn quốc (PayGOV)

Câu hỏi thường gặp

CHÚNG TÔI LUÔN SẴN SÀNG ĐỂ GIÚP ĐỠ BẠN

Để được hỗ trợ tốt nhất. Hãy gọi

CHÚNG TÔI LUÔN SẴN
SÀNG ĐỂ GIÚP ĐỠ BẠN