ngsp.gov.vn€¦ · web viewquỐc gia thÔng qua ngsp dành cho: lập trình viên hà nộ i,...
TRANSCRIPT
TÀI LIỆU HƯỚNG DẪN
KẾT NỐI CỔNG HỖ TRỢ THANH TOÁN TRỰC TUYẾN QUỐC GIA THÔNG QUA NGSP
Dành cho: Lập trình viên
Hà Nội, 2020
MỤC LỤC1. Giới thiệu............................................................................................................................................3
1.1 Mục đích.....................................................................................................................................3
1.2 Định nghĩa thuật ngữ.................................................................................................................3
2. Mô hình kết nối thanh toán...............................................................................................................3
3. Các trường hợp kết nối thanh toán..................................................................................................5
3.1 TH1: Người dùng thanh toán dịch vụ trên website dịch vụ....................................................5
3.1.1 Quy trình kết nối thanh toán.............................................................................................5
3.1.2 Sơ đồ kết nối tuần tự..........................................................................................................5
3.2 TH2: Người dùng thanh toán dịch vụ trên CHT-TTTT-QG..................................................6
3.2.1 Quy trình kết nối thanh toán.............................................................................................6
3.2.2 Sơ đồ kết nối tuần tự..........................................................................................................7
4. Đặc tả dữ liệu trao đổi.......................................................................................................................9
4.1 Danh sách các URL của CHT-TTTT-GQ cung cấp................................................................9
4.2 Kiểu dữ liệu................................................................................................................................9
4.3 Các API cung cấp.......................................................................................................................9
4.3.1 Yêu cầu thanh toán............................................................................................................9
4.3.1.1 Mô hình trao đổi dữ liệu................................................................................................9
4.3.1.2 API yêu cầu thanh toán...............................................................................................10
4.3.1.3 API nhận kết quả thanh toán của Website dịch vụ...................................................12
4.3.2 Yêu cầu truy vấn giao dịch..............................................................................................14
4.3.3 Hoàn trả giao dịch............................................................................................................16
4.3.4 Lấy thông tin hồ sơ/hóa đơn............................................................................................19
5. Các bước thiết lập kết nối với CHT-TTTT-QG............................................................................21
1. Giới thiệu1.1 Mục đích- Tài liệu này dành cho các đơn vị cung cấp dịch vụ muốn kết nối với Cổng Hỗ
trợ thanh toán trực tuyến quốc gia (CHT-TTTT-QG) để thanh toán trực tuyến. - Tài liệu này cung cấp các thông tin kết nối giữa website cung cấp dịch vụ và
CHT-TTTT-QG, bao gồm: Mô hình kết nối Quy trình kết nối Sơ đồ tuần tự Đặc tả dữ liệu trao đổi
1.2 Định nghĩa thuật ngữ
Thuật ngữ/Viết tắt Mô tảCHT-TTTT-QG Cổng Hỗ trợ thanh toán trực tuyến quốc gia.Website dịch vụ Đơn vị cung cấp dịch vụ muốn kết nối, sử dụng Cổng Hỗ trợ thanh
toán trực tuyến quốc gia CHT-TTTT-QG.NGSP (National Government Service Platform)
Hệ thống kết nối, liên thông các HTTT ở Trung ương và địa phương
LGSP(Local GovernmentService Platform)
Nền tảng tích hợp, chia sẻ cấp Bộ, cấp tỉnh
Website dịch vụ Là các phần mềm kết nối đến CHT-TTTT-QG, ví dụ các cổng Dịch vụ công của bộ ngành, của các tỉnh, các trang web thương mại điện tử …
2. Mô hình kết nối thanh toán
- Các API thanh toán của Cổng Hỗ trợ thanh toán trực tuyến quốc gia CHT-TTTT-QG được triển khai trên Trục liên thông NGSP.
- Các website dịch vụ thực hiện kết nối, chuyển hướng trang web đến CHT-TTTT-QG đều phải thông qua NGSP.
3. Các trường hợp kết nối thanh toán3.1 TH1: Người dùng thanh toán dịch vụ trên website dịch vụ 3.1.1 Quy trình kết nối thanh toán
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 NGSP, website dịch vụ gửi thông tin thanh toán của người
dùng sang CHT-TTTT-QG dưới dạng mở cửa sổ popup iframe. 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 CHT-TTTT-QG.
- Bước 3: CHT-TTTT-QG 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, CHT-TTTT-QG trả kết quả thanh toán về Website dịch vụ.
3.1.2 Sơ đồ kết nối tuần tự
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 NGSP, website dịch vụ gửi thông tin thanh toán của người dùng sang CHT-TTTT-QG dưới dạng mở cửa sổ popup iframe.
Bước 3: CHT-TTTT-QG ghi nhận Yêu cầu thanh toán và hiển thị danh sách các cổng thanh toán và ví điện tử.
Bước 4: 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 CHT-TTTT-QG.
Bước 5: CHT-TTTT-QG gửi yêu cầu thanh toán sang cổng thanh toán mà người dùng đã chọn. (Trên sơ đồ tuần tự, lấy ví dụ người dùng chọn thanh toán qua Napas).
Bước 6: Màn hình của Napas hiển thị danh sách các ngân hàng, các thẻ ATM trong nước, các thẻ tín dụng để người dùng chọn.
Bước 7: Người dùng thao tác, thực hiện các bước theo quy trình thanh toán trên cổng thanh toán Napas.
Bước 8: Sau khi hoàn tất thanh toán trên cổng Napas, giao diện của Napas redirect về trang thông báo kết quả giao dịch thanh toán của CHT-TTTT-QG (theo urlReturn gửi lên khi yêu cầu thanh toán). Đồng thời, Napas gửi kết quả thanh toán về CHT-TTTT-QG theo API ngầm ghi nhận kết quả thanh toán của CHT-TTTT-QG.
Bước 9: CHT-TTTT-QG ghi nhận và lưu lại kết quả giao dịch thanh toán vừa thực hiện. Bước 10: Thông qua NGSP, CHT-TTTT-QG redirect về trang thông báo kết quả thanh
toán dịch vụ của Website dịch vụ (theo urlReturn gửi lên khi yêu cầu thanh toán). Đồng thời, CHT-TTTT-QG gửi kết quả thanh toán về Website dịch vụ theo API ngầm ghi nhận kết quả thanh toán của Website dịch vụ.Bước 11: Website dịch vụ hiển thị kết quả thanh toán dịch vụ, kết thúc phiên giao dịch thanh toán.
3.2 TH2: Người dùng thanh toán dịch vụ trên CHT-TTTT-QG3.2.1 Quy trình kết nối thanh toán
Miêu tả sơ lược quy trình kết nối thanh toán:
Bước 1: Người dùng truy cập vào CHT-TTTT-QG, chọn thanh toán 1 dịch vụ, ví dụ: thanh toán thủ tục hành chính. Người dùng điền số biên nhận của hồ sơ/mã số hóa đơn cần thanh toán.
Bước 2: Thông qua NGSP, CHT-TTTT-QG gửi yêu cầu đến API của Website dịch vụ, lấy thông tin về hồ sơ/hóa đơn cần thanh toán. Người dùng bấm thanh toán trực tuyến hồ sơ/hóa đơn đó và chọn cổng thanh toán hoặc ví điện tử mà CHT-TTTT-QG cung cấp.
Bước 3: CHT-TTTT-QG 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, CHT-TTTT-QG trả kết quả thanh toán về API của Website dịch vụ
3.2.2 Sơ đồ kết nối tuần tự
Bước 1: Người dùng truy cập vào CHT-TTTT-QG, chọn thanh toán dịch vụ (ví dụ thanh toán thủ tục hành chính). Người dùng nhập mã số biên nhận/mã hóa đơn/mã khách hàng gắn với dịch vụ.
Bước 2: Thông qua NGSP hoặc LGSP, CHT-TTTT-QG gửi yêu cầu tra cứu thông tin hồ sơ/hóa đơn đến website dịch vụ theo mã số người dùng đã nhập.
Bước 3: CHT-TTTT-QG hiển thị thông tin hồ sơ/hóa đơn để người dùng xác nhận. Bước 4: Người dùng chọn thanh toán trực tuyến lệ phí hồ sơ/hóa đơn. Bước 5: CHT-TTTT-QG ghi nhận Yêu cầu thanh toán và hiển thị danh sách các cổng
thanh toán và ví điện tử. Bước 6: 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 CHT-TTTT-QG. Bước 7: CHT-TTTT-QG gửi yêu cầu thanh toán sang cổng thanh toán mà người dùng đã
chọn. (Trên sơ đồ tuần tự, lấy ví dụ người dùng chọn thanh toán qua Napas). Bước 8: Màn hình của Napas hiển thị danh sách các ngân hàng, các thẻ ATM trong nước,
các thẻ tín dụng để người dùng chọn. Bước 9: Người dùng thao tác, thực hiện các bước theo quy trình thanh toán trên cổng
thanh toán Napas. Bước 10: Sau khi hoàn tất thanh toán trên cổng Napas, giao diện của Napas redirect về
trang thông báo kết quả giao dịch thanh toán của CHT-TTTT-QG (theo urlReturn gửi lên khi yêu cầu thanh toán). Đồng thời, Napas gửi kết quả thanh toán về CHT-TTTT-QG theo API ngầm ghi nhận kết quả thanh toán của CHT-TTTT-QG.
Bước 11: CHT-TTTT-QG ghi nhận và lưu lại kết quả giao dịch thanh toán vừa thực hiện. Bước 12: Thông qua NGSP hoặc LGSP, CHT-TTTT-QG gửi thông báo kết quả thanh
toán qua API ngầm của Website dịch vụ. Bước 13: CHT-TTTT-QG hiển thị kết quả thanh toán dịch vụ, kết thúc phiên giao dịch
thanh toán.
4. Đặc tả dữ liệu trao đổi4.1 Danh sách các URL của CHT-TTTT-GQ cung cấp
API yêu cầu thanh toán. API yêu cầu truy vấn giao dịch. API yêu cầu hoàn trả giao dịch.
4.2 Kiểu dữ liệu
Kiểu dữ liệu Mô tả
Alphanumeric Dữ liệu kiểu số, bao gồm các ký tự in hoa, thường, ký tự số
Alpha Dữ liệu kiểu chuỗi, chỉ bao gồm các ký tự a-z & A-Z
Numeric Dữ liệu kiểu số (0-9)
4.3 Các API cung cấp4.3.1 Yêu cầu thanh toán4.3.1.1 Mô hình trao đổi dữ liệu
Request 1: Website dịch vụ redirect đến API yêu cầu thanh toán của CHT-TTTT-QG.
Request 2: CHT-TTTT-QG redirect đến API nhận kết quả thanh toán của Website dịch vụ.
4.3.1.2 API yêu cầu thanh toán- Method: POST- URL: https://api.ngsp.gov.vn/thanhtoanquocgia/1.0/paygate- Định dạng gói tin: Application/json.- Header: token phân biệt hệ thống thử nghiệm/chính thức
Tên tham số Giá trị Bắt buộc
Ví dụ
Authorization Bearer <token được cấp> ✓ -H 'Authorization: Bearer 0050d6ba-8d8b-3bc1-9197-517ed1536069'
- Request data gửi lên:
{
"partnerCode": "000.00.58.H29",
"accessKey": " f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820d",
"amount": 40000,
"orderId": "SBN_100012",
"orderInfo": "thanh toan tien dien thoai",
"serviceCode":"Pay_dcv",
"requestCode": "12357851",
"returnUrl": "http://paydate.com.vn/return",
"ipAddress":"120.72.114.122",
"checksum":"3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD "
}
- Bảng mô tả gói tin 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 đơn vị khai thác
✓ HN_Partner_12
accessKey Alphanumeric Chuỗi mã hóa xác định quyền truy cập
✓ f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820da43d4d26ec6,-360862545
returnUrlAlphanumeric Đị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
✓ SBN_100012
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
✓ 3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD
- Dữ liệu trả về: Khi gọi API thành công.
{
"error_code":"SUCCESSFUL",
"error_message":"",
"data”: {
"url":"http://103.9.0.215/paygate/napas/payment?partnerCode=000.00.58.H29&accessKey=356019473b1ed272d9ca,75780856&requestCode=1257815&orderId=Test&amount=30000&signature=b761088b86da6335befd7d7583e602f211751410ba4ce842b8b8fc718a9540fc"}
}
Khi gọi API thất bại
{
"error_code":"SIGNATURE_WRONG",
"error_message":"SIGNATURE_WRONG",
"data”: null
}
- Bảng mô tả gói tin trả về:
Tên tham số Kiểu dữ liệu Mô tả Bắt buộc
Ví dụ
error_code Alphanumeric Trạng thái hoàn trảSUCCESSFUL: thành côngFAILED: thất bạ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
4.3.1.3 API nhận kết quả thanh toán của Website dịch vụ
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, trang thanh toán của CHT-TTTT-QG 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: POST- URL: Do website dịch vụ cung cấp- Định dạng gói tin: Application/json.- Request data gửi lên:
{ "amount": 40000, "orderId": "SBN_100012", "orderInfo": "thanh toan tien dien thoai", "requestCode": "12357851", "transactionNo": "1258485", "payDate":" 20191212161254”, " paygate":"momo”, "errorCode":" 00”, "type":" pay”,"checksum":"3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD " }
- Bảng mô tả gói tin data gửi lên
Tên tham số Kiểu dữ liệu Mô tả Bắt buộc
Ví dụ
paygate Alphanumeric
Tên cổng thanh toán ✓ MoMo
transactionNo Alphanumeric
Mã giao dịch tại đơn vị chấp nhận thanh toán ✓ 3B2C7qF4qwffE997A
9DBDEA726AF7FBB4F2DBF6C2ABD
requestCode Alphanumeric
Mã yêu cầu thanh toán ✓ Pay_124
orderId Alphanumeric
Mã hóa đơn yêu cầu thanh toán
✓ 00021541HA
amount Numeric Số tiền thanh toán ✓ 10000
orderInfo Alphanumeric
Thông tin hóa đơn thanh toán
✓ Nap 100K cho so dien thoai
payDate Alphanumeric
Thời gian khách hàng thanh toán. Định dạng:
yyyyMMddHHmmss
✓ 20150924130500
errorCode Alphanumeric
Mã lỗi kết quả thanh toán ✓ 00
-00: Thành công
-#00: thất bại
type Alphanumeric
Loại
Pay: thanh toán
Refund: Hoàn trả
✓ pay
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 + paygate + orderId + amount + payDate + orderInfo + payTransId + errorCode
✓ 3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD
- Dữ liệu trả về. Khi gọi API thành công.
{
"error_code": "SUCCESSFUL",
"error_message": "Thành công",
}
Khi gọi API không thành công
{
"error_code": " FAILED",
"error_message": "Thất bại",
}
- Bảng mô tả gói tin data trả về:
Tên tham số Kiểu dữ liệu Mô tả Bắt buộc
Ví dụ
error_code Alphanumeric Trạng thái hoàn trả+ SUCCESSFUL: thành công
✓ SUCCESSFUL
+ FAILED: thất bại+ PARAM_ERROR: Dữ liệu gửi lên thiếu nội dung+SIGNATURE_WRONG: Dữ liệu không toàn vẹn
error_message Alphanumeric Thông tin error message ✓ Thành công
4.3.2 Yêu cầu truy vấn giao dịch- Method: POST- URL: https://api.ngsp.gov.vn/thanhtoanquocgia/1.0/GetOrderInfo- Định dạng gói tin: Application/json.- Header: token phân biệt hệ thống thử nghiệm/chính thức
Tên tham số Giá trị Bắt buộc
Ví dụ
Authorization Bearer <token được cấp> ✓ -H 'Authorization: Bearer 0050d6ba-8d8b-3bc1-9197-517ed1536069'
- Request data gửi lên:{ "partnerCode": "000.00.58.H29", "accessKey": " f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820d ", "orderId": "SBN_100012", "requestCode": "1278547" }
- Bảng mô tả gói tin 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
- Dữ liệu trả về Khi gọi API thành công
{
"error_code": "SUCCESSFUL",
"error_message": "",
"data": {
"requestCode": "1559563731197",
"amount": 20000,
"orderId": "778022019003000074_205",
"orderPayId": "778022019003000074_205",
"orderInfo": "null",
" transactionNo": 13148624,
"payDate": 20190603191334,
"errorCode": 0,
“type" : "pay",
"payCenter": "vnpay",
"partnerCode": "CTTQG-Partner-12",
}
}
Khi gọi API không thành công
{
"error_code": " FAILED",
"error_message": "",
"data": null
}
- Bảng mô tả gói tin data trả về:
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ịch00 : 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
ACCOUNT_NOT_EXIST: Tài khoản khai thác không tồn tại
ORDER_NOT_EXITS: Giao dịch không tồn tại
SIGNATURE_WRONG:
✓ SUCCESSFUL
Dữ liệu không toàn vẹn
error_message Alphanumeric Message thông báo ✓ Thanh cong
4.3.3 Hoàn trả giao dịch- Method: POST- URL: https://api.ngsp.gov.vn/thanhtoanquocgia/1.0/refund- Định dạng gói tin: Application/json.- Header: token phân biệt hệ thống thử nghiệm/chính thức
Tên tham số Giá trị Bắt buộc
Ví dụ
Authorization Bearer <token được cấp> ✓ -H 'Authorization: Bearer 0050d6ba-8d8b-3bc1-9197-517ed1536069'
- Request data gửi lên
{
"partnerCode": "000.00.58.H29",
"accessKey": " f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820d ",
"orderId": "SBN_100012",
"transactionNo": "1278547"
"orderInfo": "thanh toan tien dien",
"amount": 400000,
" requestCode ": "127568",
"transactionType": "02",
“checksum”: "3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726A"
}
- Bảng mô tả gói tin 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ền02 : 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
✓ 3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD
- Dữ liệu trả về Khi gọi API thành công
{
"error_code": "SUCCESSFUL",
"error_message": "",
"data": {
"requestCode": "1559563731197",
"amount": 20000,
"orderId": "778022019003000074_205",
"orderPayId": "778022019003000074_205",
"orderInfo": "null",
" transactionNo": 13148624,
"payDate": 20190603191334,
"errorCode": 0,
"payCenter": "vnpay",
“checksum”: "3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726A"
}
}
Khi gọi API không thành công
{
"error_code": " ORDER_NOT_EXITS ",
"error_message": "Thất bại",
}
- Bảng mô tả gói tin 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
ACCOUNT_NOT_EXIST: Tài khoản khai thác 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ả
✓ SUCCESSFUL
SIGNATURE_WRONG: Dữ liệu không toàn vẹn
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ịch00 : 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
✓ 3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726AF7FBB4F2DBF6C2ABD
4.3.4 Lấy thông tin hồ sơ/hóa đơn
API này phục vụ cho trường hợp 2 – Người dùng thanh toán dịch vụ trên CHT-TTTT-QG. Đây là API do đơn vị quản lý website dịch vụ xây dựng.
- Method: GET
- URL: Do website dịch vụ cung cấp- Định dạng gói tin: Application/json.- Request data gửi lên: docCode=00.H49.000001.111- Bảng mô tả gói tin data gửi lên:
Tên tham số Kiểu dữ liệu Mô tả Bắt buộc
Ví dụ
docCode Alphanumeric Mã hồ sơ cần thanh toán ✓ 00.H49.000001.111
- Dữ liệu trả về Khi gọi API thành công
{
"error_code": "SUCCESSFUL",
"error_message": "SUCCESSFUL",
"data": {
"diaChi": "Phạm Hùng Phường Mễ Trì Quận Nam Từ Liêm",
"tenNguoiNop": "Nguyễn Ngọc Thanh",
"soCMND": “146685498”,
“danhSachThanhToan”: [{
“partnerCode”: ”000.00.18.H29”,
“trangThai”: 0,
“orderId”: “29.98.H29-310519-0001_201”,
“soTien”: 40000,
“moTa”: “Mô tả"
}]
}
}
Khi gọi API không thành công
{
"error_code":"FAILED",
“error_message”: “Lấy thông tin hồ sơ thất bại",
"data”: null
}
- Bảng mô tả gói tin trả về
Tên tham số Kiểu dữ liệu Mô tả Bắt buộc
Ví dụ
diaChi Alphanumeric Địa chỉ người yêu cầu thanh toán ✓ Phạm Hùng Phường
Mễ Trì Quận Nam Từ Liêm
tenNguoiNop Alphanumeric Tên người yêu cầu thanh toán
✓ Nguyễn Ngọc Thanh
soCMNDAlphanumeric Số chứng minh nhân
dân người yêu cầu thanh toán
✓ 146685498
danhSachThanhToan JsonArray Danh sách các hoá đơn cần thanh toán
✓
partnerCode Alphanumeric Mã đơn vị yêu cầu thanh toán
✓ 000.00.18.H29
trangThai Numeric Trạng thái giao dịch:
0: Chưa thanh toán
1: Đã thanh toán
✓ 0
orderId Alphanumeric Mã hóa đơn yêu cầu thanh toán ✓ 76502201900401241_0
01
soTien Numeric Số tiền thanh toán ✓ 200000
moTa Alphanumeric Nội dung thanh toán ✓ Thanh toán cho hồ sơ có số biên nhận: 76502201900401241
error_code Alphanumeric Trạng thái request gửi lên:- SUCCESSFUL :
✓ SUCCESSFUL
thành công- FAILED : thất
bại
error_message Alphanumeric Message thông báo ✓ SUCCESSFUL
5. Các bước thiết lập kết nối với CHT-TTTT-QG- Đơn vị quản lý website dịch vụ muốn kết nối với CHT-TTTT-QG cần liên hệ với
Admin của CHT-TTTT-QG để xin cấp tài khoản, liên hệ với NGSP để cấp token truy cập
- Admin NGSP sẽ cấp token truy cập để gán vào header mỗi khi gọi các dịch vụ API được cung cấp
- Admin sẽ tạo tài khoản, cấp quyền cho đơn vụ trên CHT-TTTT-QG và cung cấp 3 thông số “partnerCode”, “accessKey” và “secretKey” cho đơn vị dùng để xác định đơn vị kết nối khi website dịch vụ gửi yêu cầu thanh toán.
- Website dịch vụ muốn kết nối với cổng thanh toán/ví điện tử nào trên CHT-TTTT-QG, cần ký hợp đồng với đơn vị quản lý cổng thanh toán/ví điện tử đó.
- Sau khi ký hợp đồng, đơn vị quản lý website dịch vụ sẽ được cung cấp tài khoản và thông tin liên kết với cổng thanh toán/ví điện tử. Đơn vị quản lý website dịch vụ cần cung cấp những thông tin này cho Admin của CHT-TTTT-QG để thiết lập liên kết cho đơn vị đó.
- Sau khi thiết lập xong, người dùng trên website dịch vụ có thể lựa chọn thanh toán trực tuyến tại cổng thanh toán/ví điện tử đó, thông qua CHT-TTTT-QG.
- Website dịch vụ phải xây dựng 2 API dưới đây và cung cấp thông tin cho Admin của CHT-TTTT-QG để thiết lập thông tin liên kết cho đơn vị đó. API nhận kết quả thanh toán của Website dịch vụ (miêu tả ở mục 4.3.1.3),
phục vụ cho trường hợp 1 của kết nối thanh toán (miêu tả ở mục 3.1). API lấy thông tin hồ sơ/hóa đơn (miêu tả ở mục 4.3.4), phục vụ cho trường hợp
2 của kết nối thanh toán (miêu tả ở mục 3.2)