I. TỔNG QUAN
1. Mô tả nghiệp vụ
- Phần mềm của đơn vị khi có nhu cầu yêu cầu thanh toán trực tuyến lên HCM LGSP.
- HCM LGSP nhận yêu cầu thanh toán của đơn vị kết nối và sẽ gửi yêu cầu thanh toán đến các ví điện tử / cổng thanh toán .
- Sau khi HCM LGSP nhận được kết quả thanh toán sẽ gửi trả thông tin thanh toán về cho các đơn vị kết nối .
2. Mục đích tài liệu
3. Phạm vi và đối tượng áp dụng
- Tài liệu này được sử dụng bởi các kỹ thuật viên của các đơn vị cần kết nối thanh toán trực tuyến
4. 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:
- PartnerCode
- AccessKey
- SecretKey
5. Thông tin dịch vụ E-payment
- Đơn vị kết nối với cổng thanh toán thành phố cần ký hợp đồng và cung cấp thông tin tài khoản cho sở Thông tin và Truyền thông các nhà cung cấp dịch vụ sau:
- MoMo
- VnPay
- NaPas
- Viettel pay
- …
II. MÔ HÌNH KẾT NỐI
1. Mô hình kết nối
Hình 1: Mô hình kết nối thanh toán trực tuyến
Miêu tả sơ lược quy trình kết nối thanh toán:
- Bước 1: Người dùng thao tác trên Website dịch vụ, chọn dịch vụ cần thanh toán và chọn thanh toán trực tuyến.
- Bước 2: Thông qua ESB, website dịch vụ gửi thông tin thanh toán của người dùng sang Cổng thanh toán. Người dùng lựa chọn một hình thức thanh toán trong danh sách các cổng thanh toán và ví điện tử cung cấp bởi cổng thanh toán .
- Bước 3: Cổng thanh toán gửi yêu cầu thanh toán đến cổng thanh toán/ví điện tử mà người dùng chọn. Người dùng thao tác các bước thanh toán trên cổng thanh toán/ví điện tử đã chọn.
Sau khi người dùng hoàn tất thanh toán, Cổng thanh toán trả kết quả thanh toán về Website dịch vụ.
2. 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ị đóng gói dữ liệu về dạng JSON.
- Bước 2: Phần mềm của đơn vị gọi đến Nền tảng HCM LGSP thông qua api kèm theo access token.
- Bước 3: Nền tảng HCM LGSP kiểm tra access token của đơn vị. Nếu thất bại sẽ trả về gói tin JSON lỗi cho phần mềm của đơn vị.
- Bước 4: Nền tảng HCM LGSP xử lý dữ liệu và trả về gói tin JSON kết quả cho phần mềm đơn vị.
III. ĐẶC TẢ API THANH TOÁN
1. Thông tin kết nối
|
Kiểu
|
Diễn giải
|
Ví dụ
|
|
Địa chỉ adapter Nền tảng HCM chính
|
Địa chỉ cổng dịch vụ dự kiến chính thức
|
https://hcmesb.tphcm.gov.vn
|
|
Địa chỉ adapter Nền tảng HCM thử nghiệm
|
Địa chỉ cổng dịch vụ thử nghiệm
|
https://hcmesb-test.tphcm.gov.vn
|
|
Authorization/Token
|
Khai báo trong Header, Là chuỗi
|
ewogICJBY2Nlc3NLZXkiOiIwNGVlZWM5NWJhMzI0YW
EzOTQ1YmVkOTUwZjc5YTNkOCIsCiAgIlNlY3JldEtleSI6Ik1EUmxa
V1ZqT1RWaVlUTXlOR0ZoTXprME5XSXRaV1E1TlRCbU56bGhNM
lE0IiwKICAiQXBwTmFtZSI6ImhjbV9zc29fYWRtaW4iLAogICJQYXJ0
bmVyQ29kZSI6ImhjbV90ZXN0X3NzbyIsCiAgIlBhcnRuZXJDb2RlQ3
VzIjoiaGNtX3Rlc3Rfc3NvIgp9
|
Bảng 1: bảng thông tin kết nối
2. API thanh toán trực tuyến
- Đường dẫn: /paygate
- Method: POST
- Đầu vào:
- Header: Authorization
- Body: chuỗi json chứa thông tin truyền vào
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
Lưu ý
|
|
1
|
partnerCode
|
String
|
partnerCode của tài khoản đơn vị khai thác
|
Bắt buộc
|
|
2
|
accessKey
|
String
|
Chuỗi mã hóa xác định quyền truy cập
|
Bắt buộc
|
|
3
|
returnUrl
|
String
|
Địa chỉ trả về khi thực hiện thanh toán xong
|
Bắt buộc
|
|
3
|
orderId
|
String
|
Mã đơn hàng cần thanh toán
|
Bắt buộc
|
|
4
|
amount
|
Int
|
Tổng số tiền cần thanh toán
|
Bắt buộc
|
|
5
|
orderInfo
|
String
|
Thông tin mô tả nội dung thanh toán
|
Bắt buộc
|
|
6
|
requestCode
|
String
|
Mã yêu cầu thanh toán
|
Bắt buộc
|
|
7
|
ipAddress
|
String
|
Địa chỉ ip khách hàng thanh toán
|
Bắt buộc
|
|
8
|
serviceCode
|
String
|
Mã dịch vụ cần thanh toán
|
Bắt buộc
|
|
9
|
checksum
|
String
|
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 + amount
|
Bắt buộc
|
Bảng 2: tham số truyền vào chuỗi json của body
Ví dụ:
|
Chuỗi json
|
|
{
"partnerCode": "000.00.18.H29",
"accessKey": " f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820d",
"amount": 40000,
"orderId": "SBN_100012",
"orderInfo": "thanh toan tien dien thoai",
"serviceCode":"hcm_dichvucong",
"requestCode": "12357851",
"returnUrl": "http://paydate.com.vn/return",
"ipAddress":"120.72.114.122",
"checksum":"3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD "
}
|
- Đầu ra:
- Chuỗi json chứa thông tin trả về , resultObject là true hoặc false
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
|
1
|
error_code
|
String
|
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
ORDER_EXITS: Giao dịch đã tồn tại
|
|
2
|
error_message
|
String
|
Thông tin error message
|
|
3
|
data
|
JSON
|
Địa chỉ trả về đường dẫn thanh toán
|
Bảng 3: tham số trả về của chuỗi json
Ví dụ:
3. API nhận kết quả thanh toán
- Khi gửi yêu cầu thanh toán, website dịch vụ phải gửi URL của API nhận kết quả thanh toán này trong trường dữ liệu returlURL. Sau khi hoàn tất thanh toán, cổng thanh toán sẽ redirect ngược về returnURL của website dịch vụ.
- Đây là API do đơn vị quản lý website dịch vụ xây dựng.
- Method: PUT
- Đầu vào:
- Body: chuỗi json chứa thông tin truyền vào
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
Lưu ý
|
|
1
|
paygate
|
String
|
Tên cổng thanh toán
|
Bắt buộc
|
|
2
|
payTransId
|
String
|
Mã giao dịch tại đơn vị chấp nhận thanh toán
|
Bắt buộc
|
|
3
|
orderId
|
String
|
Mã hóa đơn yêu cầu thanh toán
|
Bắt buộc
|
|
3
|
amount
|
Int
|
Số tiền thanh toán
|
Bắt buộc
|
|
4
|
orderInfo
|
String
|
Thông tin hóa đơn thanh toán
|
Bắt buộc
|
|
5
|
payDate
|
String
|
Thời gian khách hàng thanh toán. Định dạng:
yyyyMMddHHmmss
|
Bắt buộc
|
|
6
|
errorCode
|
String
|
Mã lỗi kết quả thanh toán
-00: Thành công
-#00: thất bại
|
Bắt buộc
|
|
7
|
type
|
String
|
Loại
Pay: thanh toán
Refund: Hoàn trả
|
Bắt buộc
|
|
8
|
checksum
|
String
|
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 : “PAYHCM1.0”+ paygate + orderId + amount + payDate +type+ ordeInfo + payTransId + errorCode
|
Bắt buộc
|
Bảng 2: tham số truyền vào chuỗi json của body
Ví dụ:
|
Chuỗi json
|
|
{
"amount": 40000,
"orderId": "SBN_100012",
"orderInfo": "thanh toan tien dien thoai",
"payTransId": "1258485",
" payDate":" 20191212161254”,
"paygate":"momo”,
"errorCode":" 00”,
"type":" pay”,
"check-sum":"3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD "
}
|
- Đầu ra:
- Chuỗi json chứa thông tin trả về , resultObject là true hoặc false
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
|
1
|
error_code
|
String
|
Mã lỗi thực hiện yêu cầu:
SUCCESSFUL: thành công
FAILED: thất bại
|
|
2
|
error_message
|
String
|
Thông tin error message
|
Bảng 3: tham số trả về của chuỗi json
Ví dụ:
|
Thành công
|
Lỗi
|
|
{
"error_code": "SUCCESSFUL",
"error_message": "Thành công",
}
|
{"error_code": " FAILED",
"error_message": "Thất bại",
}
|
4. API hoàn trả
- Đường dẫn: /refund
- Method: POST
- Đầu vào:
- Header: Authorization
- Body: chuỗi json chứa thông tin truyền vào
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
Lưu ý
|
|
1
|
partnerCode
|
String
|
Mã đơn vị
|
Bắt buộc
|
|
2
|
accessKey
|
String
|
Chuỗi mã hóa xác định quyền truy cập
|
Bắt buộc
|
|
3
|
transactionNo
|
String
|
Mã giao dịch
|
Bắt buộc
|
|
4
|
requestCode
|
String
|
Mã yêu cầu
|
Bắt buộc
|
|
5
|
amount
|
Int
|
Số tiền hoàn trả
|
Bắt buộc
|
|
6
|
orderId
|
String
|
Mã hóa đơn hoàn trả
|
Bắt buộc
|
|
7
|
orderInfo
|
String
|
Nội dung hoàn tiền
|
Bắt buộc
|
|
8
|
transactionType
|
String
|
Loại hoàn tiền
02 : hoàn tiền toàn phần
|
Bắt buộc
|
Bảng 2: tham số truyền vào chuỗi json của body
Ví dụ:
|
Chuỗi json
|
|
{
"partnerCode": "000.00.18.H29",
"accessKey": "f53abff08e6433696db0fdbe5e2e1d88f5f6e7624e4cd897db2ded626c0bee9b",
"transactionNo": "835651612",
"orderInfo": "Nội dung",
"requestCode": "1590278921647",
"amount": 10000,
"orderId": "050720190008",
"transactionType": "02"
}
|
- Đầu ra:
- Chuỗi json chứa thông tin trả về , resultObject là true hoặc false
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
|
1
|
error_code
|
String
|
Mã lỗi thực hiện yêu cầu:
SUCCESSFUL: thành công
FAILED: thất bại,
NOT_AUTHORIZED : lỗi Authorized,
ACCOUNT_NOT_EXIST : tài khoản không tồn tại
PARAM_ERROR: Dữ liệu gửi lên thiếu nội dung
ORDER_EXITS: Giao dịch đã tồn tại
|
|
2
|
error_message
|
String
|
Thông tin error message
|
|
3
|
data
|
JSON
|
Địa chỉ trả về đường dẫn thanh toán
|
Bảng 3: tham số trả về của chuỗi json
Ví dụ:
|
Thành công
|
Lỗi
|
|
{
"error_code":"SUCCESSFUL",
"error_message":"SUCCESSFUL ",
"data":"null"
|
{
"error_code": "FAILED",
"error_message": "FAILED ",
"data": null
}
|
5. API tra cứu giao dịch
- Đường dẫn: /GetOrderInfo
- Method: POST
- Đầu vào:
- Header: Authorization
- Body: chuỗi json chứa thông tin truyền vào
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
Lưu ý
|
|
1
|
partnerCode
|
String
|
partnerCode của tài khoản website dịch vụ
|
Bắt buộc
|
|
2
|
accessKey
|
String
|
Chuỗi mã hóa xác định quyền truy cập
|
Bắt buộc
|
|
3
|
payTransId
|
String
|
Mã thanh toán
|
Bắt buộc
|
|
4
|
orderId
|
String
|
Mã hóa đơn
|
Bắt buộc
|
Bảng 2: tham số truyền vào chuỗi json của body
Ví dụ:
|
Chuỗi json
|
|
{
"partnerCode": "000.00.18.H29",
"accessKey": "f53abff08e6433696db0fdbe5e2e1d88f5f6e7624e4cd897db2ded626c0bee9b",
"payTransId": "835651612",
"orderId": "050720190008"
}
|
- Đầu ra:
- Chuỗi json chứa thông tin trả về , resultObject là true hoặc false
|
STT
|
Tham số
|
Thuộc tính tham số
|
Mô tả
|
|
1
|
partnerCode
|
String
|
partnerCode của tài khoản website dịch vụ
|
|
2
|
payTransId
|
String
|
Mã giao dịch
|
|
3
|
requestCode
|
String
|
Mã yêu cầu thanh toán
|
|
4
|
amount
|
String
|
Số tiền thanh toán
|
|
5
|
paygate
|
String
|
Mã cổng nhận hoàn trả
|
|
6
|
orderId
|
String
|
Mã hóa đơn yêu cầu thanh toán
|
|
7
|
orderInfo
|
String
|
Nội dung thanh toán
|
|
8
|
payDate
|
String
|
Thời gian thanh toán
|
|
9
|
type
|
String
|
Loại
Pay: thanh toán
Refund: Hoàn trả
|
|
10
|
error_code
|
String
|
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
NOT_EXITS: Giao dịch không tồn tại
|
|
11
|
error_message
|
String
|
Message thông báo
|
Bảng 3: tham số trả về của chuỗi json
Ví dụ:
|
Thành công
|
Lỗi
|
|
{
"error_code": "SUCCESSFUL",
"error_message": "",
"data": {
"amount": "40000",
"partnerCode": "000.00.18.H29",
"orderId": "29.98.H29-310519-0001_201",
"serviceCode": "hcm_dichvucong",
"payTransId": "13333267",
"orderInfo": "Nội dung",
"errorCode": "00",
"paygate": "vnpay",
"type": "pay",
"payDate": "20200712225148"
}
}
|
{
"error_code": "FAILED",
"error_message": "",
"data": null
}
|