Giới thiệu

Bạn là nhà cung cấp các giải pháp bán hàng cho các doanh nghiệp, hãy tích hợp tính năng thanh toán PayON để tăng thêm lợi ích cho khách hàng của bạn.
Tích hợp thanh toán lên Website/APP đơn giản, linh hoạt, nhanh chóng hỗ trợ hình thức thanh toán ngay và trả góp với đầy đủ các phương thức: Thẻ quốc tế, ATM nội địa, QRcode ngân hàng, Ví điện tử ...

Thanh toán online

Thông tin kết nối:

Các bước lấy thông tin kết nối:

Bước 1: Đăng nhập PayOn bằng tài khoản bạn đã đăng ký tại đây. Nếu chưa có tài khoản, click vào đây để đăng ký

Bước 2: Chọn Tích hợp thanh toán trên Menu màn hình

Bước 3: Nhấn nút Thông tin kết nối

Bước 4: Tại đây copy các thông tin tương ứng với các key:
Url Api: URL_API - Đường dẫn API.
Http Auth User: MC_AUTH_USER - Tên Auth basic.
Http Auth Pass: MC_AUTH_PASS - Mật khẩu Http Auth basic.
Merchant ID: MC_ID - ID Merchant.
Application ID: APP_ID - ID - Ứng dụng để định danh ứng dụng tích hợp.
Secret Key: MC_SECRET_KEY - Khóa để thực hiện mã hóa tham số data trong các hàm nghiệp vụ.
( Thư viện mã hoá data : https://github.com/payon-sdk/aes-everywhere. )

Bước 5: Paste các thông tin vừa Copy vào phần tích hợp thanh toán trên ứng dụng của bạn

Phương thức giao tiếp:

API_URL Môi trường Sandbox: https://dev-api-merchant.payon.vn/v1/merchant (Test).
API_URL Môi trường Product: https://sdk.payon.vn/v1/merchant (Live).

Tham số chung & Payload Mẫu:

Mẫu Request chung:

Shell

      curl --location --request POST 'https://dev-api-merchant.payon.vn/v1/merchant/checkPayment' \
      --header 'Authorization: Basic Y2hlY2tvdXQ6MTIzNDU2' \
      --header 'Content-Type: application/json' \
      --data-raw '{
          "app_id": "160088PayON",
          "data": "U2FsdGVkX1/owhVkRzc3jYqJ0cFiyDZ+B0VE5khBHe80jre1NsCLN4GEA+HiurZeG+nwXRBd5j+LWw0rrIpAng==",
          "checksum": "59d8f1978f95ce3f67eea82d11e94712"
      }

Mẫu Response chung:

Thanh toán ngay:

Luồng thanh toán checkout:

Quy trình thực hiện thanh toán checkout với đẩy đủ các phương thức.

- Bước 1 : Khách hàng sẽ đặt một yêu cầu thanh toán tới Merchant
--> Gửi yêu cầu thanh toán đến PayOn
--> Gửi trả thông tin thanh toán lại cho Merchant
--> Chuyển hướng đến khách hàng check lại giao dịch.
- Bước 2: Khách hàng nhập thông tin thanh toán
--> Được gửi tới PayOn
--> Gửi yêu cầu trả tiền tới Bank
--> Trả lại PayOn yêu cầu nhập mã OTP đồng thời gửi mã OTP tới khách hàng.
--> Từ PayOn sẽ chuyển tới khách hàng yêu cầu nhập mã OTP.
- Bước 3: Khách hàng nhập mã OTP vừa được gửi về từ ngân hàng được sử dụng để thanh toán
--> PayOn
--> Bank sẽ kiểm tra xác thực mã OTP.
--> Bank sẽ gửi kết quả thanh toán lại cho PayOn
--> PayOn sẽ chuyển hướng trả về URL và đồng thời Notify về Merchant
--> Merchant gọi API checkpayment để kiểm tra và xác nhận giao dịch

Hàm tạo yêu cầu thanh toán:

POST {API_URL}/createOrderPaynow

Request data:

Response data:

Thanh toán QrCode:

Quy trình thực hiện thanh toán qua QrCode:

- Bước 1 : Khách hàng sẽ đặt một yêu cầu thanh toán tới Merchant
--> Yêu cầu lấy danh sách ngân hàng sang PayOn
--> PayOn gửi lại Merchant danh sách ngân hàng
--> Merchant sẽ hiển thị danh sách ngân hàng cho khách hàng.
- Bước 2 : Chọn ngân hàng để thanh toán QR Code gửi tới Merchant
--> Yêu cầu PayOn tạo QRCode
--> Gửi yêu cầu thanh toán QRCode tới Bank
--> Trả mã QRCode về PayOn
--> Trả tiếp QRCode về Merchant
--> Hiển thị mã QRCode cho khách hàng thanh toán.
- Bước 3 : Khách hàng sử dụng APP quét mã QRCode để thanh toán và điền thông tin cần thiết
--> Bank sẽ thông báo kết quả giao dịch vừa rồi về PayOn
--> Merchant gọi API checkpayment để kiểm tra và xác nhận giao dịch

Hàm API lấy danh sách ngân hàng hỗ trợ QrCode:

POST {API_URL}/getQrBankCode

Request data:

HTTP Response:

Banks:

Example:

{
  "error_code": "00",
  "error_message": "Success",
  "app_id": "appDoctor4U",
  "checksum":"3c57be97f19fcb05cd0ab3142c43f88f",
  "data": [
    {
      "Banks":{
        "ABB":{
          "code": "ABB",
          "full_name": "NH TMCP An Bình",
          "logo":"https://dev-api-merchant.payon.vn/v1/merchant/images/bank/favicon/ABB.png",
          "trade_name": "ABBank",
          "url": ""
        },
        "ACB":{
          "code": "ACB",
          "full_name": "NH TMCP Á Châu",
          "logo":"https://dev-api-merchant.payon.vn/v1/merchant/images/bank/favicon/ACB.png",
          "trade_name": "NH Á Châu",
          "url": ""
        },
      }
    }
  ]
}

Hàm tạo mã QR thanh toán:

POST {API_URL}/createQRCode

Request data:

Response data:

Example:

{
  "error_code": "00",
  "error_message": "Xử lý thành công",
  "app_id":"appDoctor4U",
  "checksum":"c1de4492b5585c2185f7cdbe47f1804e",
  "data": {
    "amount_payment": 1030000,
    "authorizationCode": "",
    "bank_code":"ABB",
    "check_order_url":"",
    "checksum":"2ec6b248ac33f8e9d09171f55981ab60",
    "currency":"VND",
    "customer_email":"giaohangtot@gmail.com",
    "customer_fullname":"Trần Văn A",
    "customer_mobile":"0999999999", "cycle":0,
    "description":"Thanh toán cho đơn hàng",
    "id":1316,
    "master_id":9999999329,
    "merchant_id":10000002220,
    "method_code":"LOCALBANK",
    "notify_url":"",
    "order_amount":1000000, "order_code":"5740b0d9-47d4-4150-adb1-9d73b61bf7ee",
    "payment_id": "POUSELPWW7LO6XV",
    "qrcode_image": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlB MVEX///8AAABVwtN+AAACXElEQVR42uyZQW7sLBCEy2LBkiNwFC72yzbKxTgKR2DJArl+dePR2JO3N7w3LCJN8kVKC6q6uoPv+Z5/8iwkeViyrAiGZGJeEeS7aSKgAlgBw1hhyALLWAIANxXge4Vlq8FwR7AZCJZtPAAUgHmTS4hlWkDvQoCKFfMB+qKCKbCJjFIm//DkngW6eFNzsQaTV5eqj+W3uscG+rGEYwV5CHD8ttPBgYVZ1Q13WKqRVmz3y3oegM1wsaJBPf4AKlaXbN44EwCYIh/c3j+F6kla/swFeMPdssnPupFmOMK/LGgOwOaG1SbVecPGJM4ayH0gYKlShciANUB0W30kq/8pmAhgNhLVGhYx0q3IiyqA39/ynwCoMEXuyUWmJsJm1hbRXkY6BOD1HZ3xYCmo6qHXy5oCkAtJmnQk5CTLyIuRTgHoOY00GB6Oqgt7zw8PA3IXbrdUy9dnL02M9mpBcwCQ4aRsFSoJTcXw1zInAGBEARo4AS1TxOFv8n8c8NqzWLpPitGzBJle0zwAbJbhhOQu7VdT2lIC8zsxTwCoLjTWR7L5Qzw0Fvm1q7qfB6gvSi9EgkL1O0K9rziGB5i1Z5nunFsBs3x5z91TAKeOKRYELCVA2gHw31yANDWdsyzbayYnL0/ueeA1d1NsvvkDQUrBRzwYHeg7kD4Rkn3dtOnS7LYrHh0491FqVM2f+yhc88MIgGdZLfsKwUfdgWi2nxBIknR6wVrhLTbPAmgK6kaqKY0fTe1xQP52qQIIJi/s+8nPNezowPl/HN0eULN93/8ZTgR8z/f8Zef/AAAA///G2IapW0+SRwAAAABJRU5ErkJggg==",
    "qrcode_pay":"0002010102122624000697042601100106393463520483585303704540410005802VN5919VIMOTECHNOLOGYJSC6005HANOI6246011003MP3262110320CTCPCN MPOS VIET NAM0704000563047E6D",
    "service_code": "PAYNOW_QRLOCALBANK_DYNAMIC",
    "service_type_code": "PAYNOW",
    "service_type_id": 2,
    "status": 1,
    "time_expired": 1613982264,
    "token_code": "7da7ba96-ef92-4dfd-9bca-363c7442d1cb",
    "transaction_id": "POP5Z86A2XW7SWZ",
    "user_id": 0,
    "userfee": 1
  }
}

Trả góp:

Hàm lấy danh sách ngân hàng hỗ trợ:

POST {API_URL}/getBankInstallment

Response data:

Banks:

Example:

{
  "error_code":"00",
  "error_message":"Success",
  "app_id":"appDoctor4U",
  "checksum":"112714fd905178ab2e383e2d26d428cd",
  "data":{
    "Banks":{ 
      "ACB":{
        "code":"ACB",
        "trade_name":"NH Á Châu",
        "full_name":"NH TMCP Á Châu",
        "logo":"https://dev-api-merchant.payon.vn/v1/merchant/images/bank/favicon/ACB.png",
        "installment_rule":"- Nếu KH giao dịch bằng thẻ phụ, thì chủ thẻ chính cần liên hệ thông báo với NH về GD Trả Góp qua VIMO",
        "cycle":["3","6","9","12"],
        "installment_card_type":["visa", "mastercard", "jcb"],
      },
      "VPB":{
        "code":"VPB",
        "trade_name":"VPBank",
        "full_name":"NH TMCP Việt Nam Thịnh Vượng",
        "logo":"https://dev-api-merchant.payon.vn/v1/merchant/images/bank/favicon/VPB.png",
        "url":"",
        "installment_rule":"- Thẻ Doanh nghiệp sẽ Không được Ngân hàng hỗ trợ Trả góp.\u003cbr\u003e\r\n- Chủ thẻ Không cần liên hệ, PayOn sẽ liên hệ Ngân hàng để chuyển đổi Trả góp.",
        "cycle":["3","6","9","12"],
        "installment_card_type":["visa", "mastercard"],
      }
    }
  }
} 

Hàm thông tin phí:

POST {API_URL}/getFeeInstallmentv2

Request data:

Response data:

Example:

{
    "error_code": "00",
    "error_message": "Xử lý thành công",
    "app_id": "appDoctor4U",
    "checksum": "4cbdaab20f6e0c8fd50d6366d118ae48",
    "data": {
        "3": {
            "amount_payment": 10000000,
            "fee": 151000,
            "receiver_fee": 151000,
            "sender_fee": 0,
            "userfee": 2
        },
        "6": {
            "amount_payment": 10000000,
            "fee": 630000,
            "receiver_fee": 630000,
            "sender_fee": 0,
            "userfee": 2
        },
        "9": {
            "amount_payment": 10000000,
            "fee": 730000,
            "receiver_fee": 730000,
            "sender_fee": 0,
            "userfee": 2
        }
    }
}

Hàm tạo yêu cầu thanh toán:

POST {API_URL}/createOrderInstallment

Request data:

Response data:

Example:

{
  "url_checkout":"https://dev-api-merchant.payon.vn/v1/merchant/method/0b158186-d1c5-45e0-a97a745e0 1bacf52",
  "time_expired":1623922287,
  "merchant_request_id":"31fd1271-a7b6-4b45-a299-500e5b713d6d",
  "payment_id":"POOJ93HUCFPNWUC",
  "payment_token":"0b158186-d1c5-45e0-a97a-745e01bacf52",
  "status":1
}

Thông báo kết quả đơn hàng:

Post from JSON data:

Data Array:

Trạng thái đơn hàng:

Chi tiết giao dịch:

Hàm kiểm tra giao dịch:

POST {API_URL}/checkPayment

Request data:

Response data:

Trạng thái giao dịch:

Bảng mã lỗi:

Thông tin test:

Thông tin thẻ nội địa:

Thông tin thẻ quốc tế:

SDK PayOn:

- SDK sử dụng cho PHP : https://github.com/nextpaygroup/payon-php-sdk.
- SDK sử dụng cho Java : https://github.com/nextpaygroup/payon-java-sdk.

Plugin WordPress:

Plugin trong WordPress là một hay nhiều đoạn code được bổ sung vào mã nguồn của website. Plugin được xem là phần mở rộng của trang website giúp người dùng bổ sung thêm nhiều tính năng khác cho trang WordPress của mình. Plugin PayOn PaymentGateway hỗ trợ tích hợp cổng thanh toán PayOn vào website Wordpress dễ dàng và nhanh chóng, khách hàng có thể thanh toán bằng hình thức trả ngay hoặc trả góp 0% tiện lợi.

Link cài đặt plugin:https://wordpress.org/plugins/payon-paymentgateway/.
Hướng dẫn tạo và xác thực tài khoản PayOn tại đây.
Hướng dẫn liên kết thanh toán PayOn trên Woocommerce tại đây.

Thanh toán Quẹt thẻ

Mục đích tài liệu

Tài liệu mô tả và hướng dẫn thực hiện tích hợp kết nối kỹ thuật giữa hệ thống thanh toán của Đơn vị chấp nhận thẻ (ĐVCNT) với giải pháp thanh toán trên di động MPOS.

Yêu cầu thanh toán sẽ được gửi từ server của đối tác tới ứng dụng mobile MPOS một cách tự động. Sau khi tiến hành thanh toán trên ứng dụng MPOS, trạng thái của hóa đơn sẽ được cập nhật tự động về máy POS của Đơn vị chấp nhận thẻ.

Điều kiện kết nối

• Là ĐVCNT của MPOS.VN đang hoạt động .
• Cấu hình tích hợp thanh toán trên hệ thống MPOS.VN đã được MPOS.VN xác thực.

Phương thức giao tiếp

Mọi giao tiếp từ MPOS SERVER đến hệ thống của Đơn vị chấp nhận thẻ đều qua kết nối Internet, sử dụng HTTPS protocol và REST API.

API_URL Môi trường Sandbox: http://devapi.mpos.vn/supermarket/ (Test).
API_URL Môi trường Product: https://api.mpos.vn/supermarket/ (Live).

Tất cả yêu cầu truy vấn API từ MPOS đến hệ thống của Đơn vị chấp nhận thẻ (ĐVCNT) đều được mã hoá:

• Sử dụng AES128 để mã hoá/giải mã.
• Độ dài key 16 bytes.
  

Mã hoá:
- Tạo chuỗi JSON với các thông tin cần thiết cho mỗi Request.
- Mã hoá chuỗi JSON với Key đã được cấp.
- Encode chuỗi mã hoá thành Base64 để thực hiện gửi và nhận giữa 2 hệ thống.

Giải mã:
- Decode Base64 từ dữ liệu nhận được.
- Giải mã chuỗi Decode trước đó bằng Key đã được cấp thu được chuỗi JSON.
- Key AES sẽ được MPOS cấp tại trang quản trị của Đơn vị chấp nhận thẻ.

• Key AES sẽ được MPOS cấp tại trang quản trị của ĐVCNT.

Thanh toán Push Payment

Hình bên dưới mô tả luồng giao tiếp thanh toán đơn hàng được tạo từ ứng dụng của ĐVCNT và sử dụng hình thưc quẹt thẻ trên app MPOS để xác nhận thanh toán:

Tạo đơn hàng thanh toán

• REQUEST reqData - Các trường trong chuỗi JSON reqData sử dụng:

• RESPONSE resData - Các trường trong chuỗi JSON resData sử dụng:

Hủy/Xóa hóa đơn

• REQUEST reqData - Các trường trong chuỗi JSON reqData sử dụng:

• RESPONSE resData - Các trường trong chuỗi JSON resData sử dụng:

Nhận thông tin thanh toán và cập nhật trạng thái giao dịch

ĐVCNT cung cấp API cho phép MPOS gửi dữ liệu thanh toán cùng mã hoá đơn cho ĐVCNT khi thay đổi trạng thái của giao dịch. ĐVCNT cung cấp endpoint này để MPOS cấu hình trên hệ thống.

Api kiểm tra giao dịch

API cho phép đối tác kiểm tra trạng thái thanh toán của hóa đơn

• REQUEST reqData - Các trường trong chuỗi JSON reqData sử dụng:

• RESPONSE resData - Các trường trong chuỗi JSON resData sử dụng:

Kết nối dịch vụ VAS

Billing ( điện, nước, tài chính.. ) , Topup ( Telco, Game, Data, ...) , Pincode , Ticket ( Tàu, xe, xem phim ..)

Thông tin kết nối VAS

• Phương thức Restful
• Thông tin kết nối
  • URL_API
  • MC_CODE
  • MC_AUTH_USER
  • MC_AUTH_PASS
  • MC_ENCRYPT_KEY
  • MC_CHECKSUM_KEY

Request Payload

Response Payload

Kiểm tra số dư tài khoản đối tác

Request data

Response data là object chứa các tham số:

Kiểm tra thông tin kết nối

Đang cập nhật

Thanh toán hóa đơn

Truy vấn hóa đơn - Hàm querybill

Request data

Response data là object chứa các tham số:

billDetail là array chứa các tham số:

customerInfo là object chứa các tham số:

Chú ý: Ở API truy vấn trả về thông tin otherInfo có giá trị addFee thì khi gọi thanh toán 1 phần cần phải truyền lên addFee được tính toán theo chính sách từng thời điểm (giá trị này MC tự tính toán)

Thanh toán hóa đơn - Hàm paybillv2

Request data

Response data là object chứa các tham số:

billDetail là array chứa các tham số:

customerInfo là object chứa các tham số:

Thanh toán hóa đơn – Hàm paybillpartial

Chú ý: Chỉ áp dụng với các trường hợp thanh toán một phần – hóa đơn tài chính

Request data

Response data là object chứa các tham số:

billDetail là array chứa các tham số:

customerInfo là object chứa các tham số:

Truy vấn phụ phí – Hàm getaddfee

Request data

Response data

Kiểm tra giao dịch – Hàm checkbilltransaction

Request data

Response data là array chứa các tham số:

Kiểm hủy giao dịch – hàm revertbill

- Áp dụng hàm reverbill với giao dịch : thời gian paybill < 15 phút, giao dịch chưa gạch nợ bởi đơn vị điện lực

- Áp dụng với dịch vụ FE, thời gian xử lý giao dịch hoàn khoản 3 ngày từ khi nhà cung cấp nhận được lệnh reverbill

Request data

Response data là object chứa các tham số:

billDetail là array chứa các tham số:

customerInfo là object chứa các tham số:

Một số lưu ý

Thanh toán hóa đơn điện

Các loại hóa đơn điện

Đối với EVN Miền Bắc

• Một KH có thể có nhiều hóa đơn các kỳ khác nhau, KH phải thanh toán kỳ xa nhất trước. (hóa đơn kỳ xa là hóa đơn có billID nhỏ nhất)

• KH có thể có nhiều hóa đơn cùng 1 kỳ, cho phép KH lựa chọn hóa đơn thanh toán

• Áp dụng hàm reverbill với giao dịch : thời gian paybill < 15 phút, giao dịch chưa gạch nợ bởi đơn vị điện lực

Đối với EVN Hồ Chí Minh

• Khi thanh toán không truyền bill_id, thực hiện thanh toán theo thứ tự bill HCM trả về

Đối với EVN Miền Trung

• otherService coi như 1 bill cần thanh toán và không ràng buộc

• Cho phép thanh toán từng bill, ưu tiên thanh toán bill ở billDetails trước otherService

Đối với EVN Miền Nam

• Một KH có thể có nhiều hóa đơn các kỳ khác nhau, KH phải thanh toán kỳ xa nhất trước. (hóa đơn kỳ xa là hóa đơn có billID nhỏ nhất)

• Một KH 1 kỳ có nhiều hóa đơn : TD, VC… Thì thanh toán hóa đơn có loại TD trước

• Áp dụng hàm reverbill với giao dịch : thời gian paybill < 15 phút, giao dịch chưa gạch nợ bởi đơn vị điện lực

Thanh toán hóa đơn nước

Đang cập nhật...

Thanh toán hóa đơn tài chính

• Bill tài chính giới hạn 1 gd/bill/ngày và 2 gd/bill/tháng (với case thanh toán hóa đơn từng phần)
• Số tiền thanh toán tối thiểu: 50.000đ / tối đa 50.000.000
• FECREDIT , HOME, Mcredit, Mirae Asset, CASH24 là cho thanh toán từng phần

Với những dịch vụ được refund: FEC, CASH24 thời gian phản hồi là 3 ngày làm việc kể từ khi nhận được yêu cầu, sẽ phối hợp với đối tác tài chính để có kết quả sớm nhất

Nạp tiền tài khoản điện thoại/game/data

Mua dịch vụ topup điện thoại/ game – Hàm topup

Request data

Response data là object chứa các tham số:

Mua dịch vụ topupdata – hàm topupdata

Request data

Response data là object chứa các tham số:

Kiểm tra giao dịch – hàm checktopuptransaction

Request data

Response data là array chứa các tham số:

Mua mã thẻ điện thoại/game

Mua dịch vụ mã thẻ – hàm pincode

Request data

Response data là object chứa các tham số:

cards là chứa các tham số:

Kiểm tra giao dịch – hàm getpincodetransaction

Request data

Response data là array chứa các tham số:

Bảng mã lỗi VAS