ngsp.gov.vn … · Web viewTÀ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,

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

Mã lỗi thực hiện yêu cầu:SUCCESSFUL: thành côngFAILED: thất bại,PARAM_ERROR: Dữ liệu gửi lên thiếu nội dungSIGNTURE_WRONG: Dữ liệu không toàn vẹnAC-COUNT_NOT_EXIST: Tài khoản không tồn tạiPART-NER_NOT_EXIST: Đơn vị kết nối không tồn tạiACCESS-INFO_NOT_EXIST: Thông tin truy cập không tồn tạiSER-

✓ SUCCESSFUL

VICE_NOT_EXIST: Dịch vụ không tồn tạiORDER_EXITS: Giao dịch đã tồn tại

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


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: Thành công

-#00: thất bại

✓ 00

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


- 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ề:


Ví dụ

error_code Alphanumeric Trạng thái hoàn trả+ SUCCESSFUL: thành công+ 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

✓ SUCCESSFUL

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


Ví dụ


- Request data gửi lên:{ "partnerCode": "000.00.58.H29",

"accessKey": " f6047c5b34702d1edd05926c421317f62a58edc3e1c06ce74820d ", "orderId": "SBN_100012", "requestCode": "1278547",

"checksum": "7afd6ccff4646e6d822c56c7554beb0a57f408e6f9b5c568c3cd44797ab004e" }

- Bảng mô tả gói tin data gửi lên:


Ví dụ

partnerCode Alphanumeric partnerCode của tài khoản website dịch vụ

✓ CTTQG-Partner-12


✓ 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

- Dữ liệu trả về Khi gọi API thành công

{


"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",

}

}


{

"error_code": " FAILED",


"data": null

}

- Bảng mô tả gói tin data trả về:


Ví dụ



transactionNo Alphanumeric Mã giao dịch ✓ Payment123



payCenter Alphanumeric

Mã cổng nhận hoàn trả ✓ Momo


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

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

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


Ví dụ


- 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


Ví dụ




✓ 1a2b3c4d5e6f7g8hi9j

transactionNo Alphanumeric Mã giao dịch ✓ Payment123




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



{



"data": {

"requestCode": "1559563731197",

"amount": 20000,

"orderId": "778022019003000074_205",

"orderPayId": "778022019003000074_205",

"orderInfo": "null",

" transactionNo": 13148624,

"payDate": 20190603191334,

"errorCode": 0,

"payCenter": "vnpay",

“checksum”: "3B2C7C400EB89625A82B9F92B82863F4E997A9DBDEA726A"

}

}


{

"error_code": " ORDER_NOT_EXITS ",

"error_message": "Thất bại",

}

- Bảng mô tả gói tin trả về


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ị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


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:


Ví dụ

docCode Alphanumeric Mã hồ sơ cần thanh toán ✓ 00.H49.000001.111


{


"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ả"

}]

}

}


{

"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ề


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 :

thành công- FAILED : thất

bại

✓ SUCCESSFUL

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)

Documents

ngsp.gov.vn … · Web viewTÀ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,