account_circle Toanph date_range 24/08/2020

Hệ thống hỗ trợ thanh toán dịch vụ công trực tuyến toàn quốc

Các trường hợp kết nối thanh toán

TH1: Người dùng thanh toán dịch vụ trên website dịch vụ

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 PayGov 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 PayGov.

• Bước 3: PayGov 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, PayGov trả kết quả thanh toán về Website dịch vụ.

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 PayGov dưới dạng mở cửa sổ popup iframe.

• Bước 3: PayGov 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 PayGov.

• Bước 5: PayGov gửi yêu cầu thanh toán sang trung gian thanh toán mà người dùng đã chọn.

• Bước 6: Màn hình của trung gian thanh toán 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 trung gian thanh toán.

• Bước 8: Sau khi hoàn tất thanh toán trên trung gian thanh toán, giao diện của trung gian thanh toán redirect về trang thông báo kết quả giao dịch thanh toán của PayGov (theo urlReturn gửi lên khi yêu cầu thanh toán). Đồng thời, trung gian thanh toán gửi kết quả thanh toán về PayGov theo API ngầm ghi nhận kết quả thanh toán của PayGov.

• Bước 9: PayGov 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, PayGov 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, PayGov 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.

TH2 Người dùng thanh toán dịch vụ trên PayGov

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 PayGov, 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, PayGov 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à PayGov cung cấp.

• Bước 3: PayGov 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, PayGov trả kết quả thanh toán về API của Website dịch vụ

Sơ đồ kết nối tuần tự

• Bước 1: Người dùng truy cập vào PayGov, 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, PayGov 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: PayGov 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: PayGov 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 PayGov.

• Bước 7: PayGov 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 PayGov (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ề PAYGOV theo API ngầm ghi nhận kết quả thanh toán của PayGov.

• Bước 11: PayGov 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, PayGov 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: PayGov hiển thị kết quả thanh toán dịch vụ, kết thúc phiên giao dịch thanh toán.

TH3: Người dùng thanh toán dịch vụ trên Trung gian 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 trung gian thanh toán, nhập mã biên nhận hồ sơ thanh toán lệ phí trực tuyến và lựa chọn Đơn vị kết nối đã tích hợp với Cổng Hỗ trợ thanh toán quốc gia.

• Bước 2: Trung gian thanh toán gửi yêu cầu đến API của PayGov lấy thông tin hồ sơ và mã đối tác đã đăng ký với trung gian thanh toán.

• Bước 3: PayGov gửi yêu cầu đến API của Đơn vị kết nối để lấy thông tin hồ sơ.

• Bước 4: Trung gian thanh toán xử lý giao dịch, sau đó trả về kết quả thanh toán cho Cổng Hỗ trợ thanh toán quốc gia.

• Bước 5: Cổng Hỗ trợ thanh toán quốc gia trả về kết quả thanh toán cho Đơn vị kết nối.

Sơ đồ kết nối tuần tự

• Bước 1: Người dùng thao tác trên trung gian thanh toán, nhập mã biên nhận hồ sơ muốn thanh toán trực tuyến và chọn Đơn vị kết nối đã tích hợp với PayGov.

• Bước 2: Trung gian thanh toán gửi mã biên nhận hồ sơ của người dùng sang PayGov để lấy thông tin chi tiết của hồ sơ.

• Bước 3: PayGov gửi yêu cầu lấy thông tin chi tiết hồ sơ tới Đơn vị kết nối.

• Bước 4: Đơn vị kết nối tiếp nhận mã biên nhận hồ, thực hiện lấy thông tin chi tiết và trả về cho PayGov.

• Bước 5: PayGov trả về thông tin chi tiết của mã biên nhận hồ sơ và thông tin kết nối thanh toán của Đơn vị kết nối.

• Bước 6: Trung gian thanh toán tiếp nhận thông tin chi tiết của hồ sơ và thông tin kết nối thanh toán của Đơn vị kết nối, hiển thị thông tin hồ sơ và số tiền cần thanh toá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 trung gian thanh toán.

• Bước 8: Trung gian thanh toán ghi nhận và lưu lại kết quả giao dịch thanh toán của hồ sơ vừa thực hiện.

• Bước 9: Trung gian thanh toán hiển thị kết quả thanh toán hồ sơ cho người dùng, đồng thời trả về kết quả thanh toán cho PayGov (gửi đến khi thành công).

• Bước 10: PayGov ghi nhận và lưu lại kết quả thanh toán của hồ sơ, trả về kết quả thanh toán cho Đơn vị kết nối (đến khi thành công).

• Bước 11: Đơn vị kết nối ghi nhận kết quả thanh toán và cập nhật lại trạng thái hồ sơ.

Mô tả các API

1. API yêu cầu thanh toán

1. Request Header

• URL: ***/api/PayGov/YeuCauThanhToan
• Method:: POST
• Authorization: Bearer 'token'
• Content-Type: application/json

2. Request body

{
    "partnerCode": "partnerCode của tài khoản đơn vị khai thác",
    "accessKey": "Chuỗi mã hóa xác định quyền truy cập",
    "amount": "Tổng số tiền cần thanh toán",
    "orderId": "Mã đơn hàng cần thanh toán.orderId = docCode + '-' + < số lượt thanh toán của hồ sơ >",
    "orderInfo": "Thông tin mô tả nội dung thanh toán",
    "serviceCode":"Mã dịch vụ cần thanh toán",
    "requestCode": "Mã yêu cầu thanh toán",
    "returnUrl": "Địa chỉ trả về khi thực hiện thanh toán xong",
    "ipAddress":"Địa chỉ ip khách hàng thanh toán",
    "checksum":"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"
}

3. Response body

{  
"code": "Mã trạng thái HTTP trả về", 
"status": "Mã trạng thái xử lý trả về", 
"correlationId": "Mã correlationId dành cho người lập trình trong quá trình kiểm tra kết nối",
"response": "Chuỗi Json kết quả dữ liệu được trả về từ hệ thống " 
}

2. API yêu cầu truy vấn giao dịch

1. Request Header

• URL: ***/api/PayGov/ThongTinThanhToan
• Method:: POST
• Authorization: Bearer 'token'
• Content-Type: application/json

2. Request body

{
    "partnerCode": "partnerCode của tài khoản đơn vị khai thác",
    "accessKey": "Chuỗi mã hóa xác định quyền truy cập",
    "orderId": "Mã đơn hàng cần thanh toán.orderId = docCode + '-' + < số lượt thanh toán của hồ sơ >",
    "requestCode": "Mã yêu cầu thanh toán",
     "checksum":"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"
}

3. Response body

{  
"code": "Mã trạng thái HTTP trả về", 
"status": "Mã trạng thái xử lý trả về", 
"correlationId": "Mã correlationId dành cho người lập trình trong quá trình kiểm tra kết nối",
"response": "Chuỗi Json kết quả dữ liệu được trả về từ hệ thống " 
}

3. API hoàn trả giao dịch

1. Request Header

• URL: ***/api/PayGov/HoanTraGiaoDich
• Method:: POST
• Authorization: Bearer 'token'
• Content-Type: application/json

2. Request body

{
    "partnerCode": "partnerCode của tài khoản đơn vị khai thác",
    "accessKey": "Chuỗi mã hóa xác định quyền truy cập",
    "orderId": "Mã đơn hàng cần thanh toán.orderId = docCode + '-' + < số lượt thanh toán của hồ sơ >",
    "transactionNo": "Mã giao dịch",
    "orderInfo": "Nội dung hoàn tiền",
    "amount": "Số tiền thanh toán",
    "requestCode": "Mã yêu cầu thanh toán",
    "transactionType": "Loại hoàn tiền 02 : hoàn tiền toàn phần",
    "checksum": "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"
}

3. Response body

{  
"code": "Mã trạng thái HTTP trả về", 
"status": "Mã trạng thái xử lý trả về", 
"correlationId": "Mã correlationId dành cho người lập trình trong quá trình kiểm tra kết nối",
"response": "Chuỗi Json kết quả dữ liệu được trả về từ hệ thống " 
}

3. API 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 PAYGOV. Đây là API do đơn vị quản lý website dịch vụ xây dựng.

1. Request Header

• URL:: Đơn vị gửi lại URL
• Method:: GET
• Authorization: Bearer 'token'
• Content-Type: application/json

2. Request Params

    docCode: "Mã hồ sơ cần thanh toán"

3. Response body

Trả về khi thành công

{
    "error_code": "SUCCESSFUL",
    "error_message": "SUCCESSFUL",
    "data": {
        "diaChi": "Địa chỉ người yêu cầu thanh toán",
        "tenNguoiNop": "Tên người yêu cầu thanh toán",
        "soCMND": "Số chứng minh nhân dân người yêu cầu thanh toán",
        "danhSachThanhToan": [{ // Danh sách các hoá đơn cần thanh toán
            "partnerCode": "Mã đơn vị yêu cầu thanh toán",
            "trangThai": "Trạng thái giao dịch", //0: Chưa thanh toán; 1: Đã thanh toán
            "orderId": "Mã hóa đơn yêu cầu thanh toán",
            "soTien": "Số tiền thanh toán",
            "moTa": "Nội dung thanh toán"
            }]
        }
}

Trả về khi thất bại

{
    "error_code":"FAILED",
   "error_message": "Lấy thông tin hồ sơ thất bại",
   "data": null
}