Dịch vụ thanh toán

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

Thành công

Lỗi

{

"error_code":"SUCCESSFUL",

"error_message":"",

"data":{

"url": "http://103.9.0.215/paygate/napas/payment?
partnerCode=000.00.18.H29
&access-Key=356019473b1ed272d9ca,75780856
&requestCode=1257815
&orderId=Test
&amount=30000
&signature=
b761088b86da6335befd7d7583e602f211751410
ba4ce842b8b8fc718a9540fc
"

}

{

    "error_code": "FAILED",

    "error_message": "",

    "data": null

}         

3. API nhận kết quả thanh toán

  • Khi gửi yêu cầu thanh toán, website dch 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 qun lý website dch v xây dng.
  • 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

}         

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

  • DacTaiLieu_APIKetnoiThanhToanTructuyen_v1.0.docx