Tích hợp Payment Pro

# Giới thiệu

# Sơ đồ tích hợp

# Tài liệu mô tả API

# Các bước tích hợp

# Giới thiệu

Hệ thống thanh toán Tích hợp Pro cho phép các lập trình viên tích hợp hệ thống thanh toán chấp nhận thẻ ngân hàng trực tiếp trên website Thương mại điện tử của người bán, do đó người mua sẽ chọn phương thức thanh toán trực tiếp trên site của người bán mà không có sự xuất hiện của Bảo Kim, phương thức tích hợp Pro giúp người bán đem lại cho người mua trả nghiệm thân thiện và đơn giản.

# Sơ đồ tích hợp

# Mô tả về API lấy danh sách ngân hàng

API lấy danh sách ngân hàng được sử dụng để lấy danh sách các ngân hàng mà người bán đang được cung cấp để thanh toán đơn hàng của mình.

  • Địa chỉ Webservices: /payment/rest/payment_pro_api/get_seller_info
  • Request method: Get
Tham số đầu vào
Tên Kiểu Bắt buộc? Mô tả
business string Y email tài khoản bán
Dữ liệu trả về
{
  "seller_account": { //===THÔNG TIN TÀI KHOẢN NGƯỜI BÁN===
    "id": "1000005", //mã tk
    "email": "1@bk.vn", //email tk
    "phone_no": "84943972259", //phone no
    "name": "Firzen Le", //tên tk
    "company_name": "", //tên cty (nếu có)
    "account_type_id": "2",
    "status": "Đã xác thực", //trạng thái tài khoản
    "balance": "5329190.00",
    "freeze_balance": "524823422.96",
    "point": "2315000.00",
    "freeze_point": "0.00",
    "km1": 0,
    "freeze_km1": 0,
    "account_type": "Doanh nghiệp" //loại tài khoản
  },
  "bank_payment_methods": [ //===DANH SÁCH PHƯƠNG THỨC THANH TOÁN NGÂN HÀNG===
    {
      "id": "48", //mã (bank_payment_method_id)
      "complete_time": "5 -10 ", //thời gian hoàn thành
      "payment_method_type": "5", //loại phương thức
      "next_action": "display_guide",
      "name": "Ngân hàng Đông Nam Á",  //tên phương thức
      "bank_id": "101",
      "fix_fee": "0.00", //phí cố định (ngân hàng)
      "percent_fee": "0.00", //phí % (ngân hàng)
      "min_fee": "0.00", //giới hạn mức sàn phí giao dịch (0 là không có giới hạn)
      "max_fee": "0.00", //giới hạn mức trần phí giao dịch (0 là không có giới hạn)
      "fee_currency_code": "VND", //đơn vị tiền tệ tính phí
      "fee_configs": [
        {
          "bank_payment_method_id": "48", // Mã phương thức thanh toán
          "amount_from": "0.00", //Số tiền thanh toán từ
          "amount_to": "0.00", //Số tiền thanh toán đến
          "fix_fee": "0.00", //Phí cố định
          "percent_fee": "0.00", //Phí phần trăm theo giao dịch
          "min_fee": "0.00",
          "max_fee": "0.00",
          "fee_currency_code": "VND"
        }
      ],
      "logo_url": "http://kiemthu.baokim.vn/banks/seabank_1268290352.jpg"
    },
    ...
  ]
}

# Mô tả về API thanh toán qua thẻ ngân hàng

API thanh toán qua thẻ ngân hàng là api được gọi khi website của khách hàng cần thanh toán cho một đơn hàng thông qua hệ thống của Bảo Kim.

  • Địa chỉ Webservices: /payment/rest/payment_pro_api/pay_by_card
  • Request method: POST

# Tham số đầu vào

Tên Kiểu Bắt buộc Mô tả
Thông tin đơn hàng    
order_id string Y mã đơn hàng
business string Y email tài khoản người bán
total_amount double Y tổng tiền đơn hàng
order_description string N mô tả đơn hàng
shipping_fee double N phí vận chuyển, default: 0
tax_fee double N Thuế, default: 0
url_cancel string N url redirect khi hủy thanh toán
url_success string N url redirect sau khi thanh toán thành công
url_detail string N url xem chi tiết đơn hàng
Thông tin người mua    
payer_name string Y tên người mua
payer_email string Y email người mua
payer_phone_no string Y số điện thoại người mua
payer_address string N địa chỉ người mua, với định dạng: ĐỊA CHỈ | THÀNH PHỐ
message string N thông điệp mua hàng
thông tin về phương thức thanh toán    
bank_payment_method_id int Y mã phương thức thanh toán ngân hàng
transaction_mode_id int N 1: trực tiếp / 2: an toàn, default: 1
escrow_timeout int N số ngày tạm giữ (nếu thanh toán an toàn), default: 0
mui string N mode giao diện hiển thị guide nạp tiền (gồm 3 mode: charge/base/iframe), default: charge

# Dữ liệu trả về

HTTP status code 200 - thành công

Kết quả trả về thành công, phía client cần xử lý 2 khả năng sau đây:

  • TH1 next_action==redirect: người dùng sử dụng phương thức thanh toán online trên ngân hàng ⇒ cần phải redirect sang ngân hàng/cổng thanh toán trung gian:
{
  "next_action": "redirect", //Redirect trình duyệt người dùng
  "redirect_url": "https://www.baokim.vn/thanh-toan/bank?rvid=1005292",
  "rv_id":"100001" //Mã phiếu thu
}
  • TH2 next_action==display_guide: người dùng sử dụng phương thức thanh toán thủ công (vd: chuyển khoản ngân hàng, …) hệ thống cần hiển thị hướng dẫn nạp tiền cho khách
{
  "next_action": "display_guide", //Hiển thị hướng dẫn nạp tiền
  "guide_url": "https://www.baokim.vn/thanh-toan/guide/ib?oid=1962",
  "rv_id":"100002" //Mã phiếu thu
}

Đối với trường hợp 1 khi giao dịch thành công, Bảo Kim tiến hành redirect về website merchant theo đường dẫn trong biến url_success trong đơn hàng


  Tên trường

Kiểu dữ liệu

Bắt buộc

Mô tả
 order_id
String(45)
 Y 
Mã hóa đơn thanh toán submit lên baokim.vn
transaction_id
String(13)
 Y 
Mã giao dịch thanh toán trên baokim.vn
created_on
Integer
 Y 
Thời điểm tạo giao dịch trên hệ thống baokim.vn. Tính bằng số giây kể từ thời điểm 1/1/1970 12:00 AM (ví dụ 1283220985 = 31-08-2010:16:25 AM)
payment_type
Integer
 Y 
Hình thức thanh toán: 1: thanh toán trực tiếp, 2: thanh toán an toàn
transaction_status
Integer
 Y 
Trạng thái giao dịch
total_amount
Double
Y
Tổng số tiền người mua thanh toán (có thể bao gồm thêm phí khi thanh toán qua internet banking, phí chuyển tiền…)
net_amount
Double
Y
Số tiền người bán thực nhận
fee_amount
Double
Y
Phí dịch vụ baokim thu
merchant_id
Integer
Y
Mã website tích hợp
customer_name
String(100)
Y
Tên người thanh toán
customer_email
String(45)
Y
Email người thanh toán
customer_phone
String(45)
Y
Số điện thoại người thanh toán
customer_address
String(255)
N
Địa chỉ người thanh toán
Checksum
String(32)
Y
Chuỗi bảo mật tránh giả mạo thông tin (cách thức tạo ghi ở bên dưới)
HTTP status code khác 200 - error
{
 "error": "thông điệp lỗi",
 "error_code": "0xF00" //mã lỗi
}

# Mô tả về API kiểm tra trạng thái đơn hàng

  • Địa chỉ Webservices: /payment/order/queryTransaction
  • Request method: Get
Tham số đầu vào
Tên trường kiểu dữ liệu Bắt buộc Size Mô tả
order_id string N 10 Order id
transaction_id string Y 255 BaoKim transaction id
merchant_id double Y 10 Website code integrated
checksum string N 255 String encrypts all information
Hướng dẫn tạo checksum
  • Sắp xếp mảng tham số giao tiếp giữa 2 bên theo tên trường tham số (key sort)
  • Tạo dữ liệu chuẩn bị mã hóa bằng cách ghép xâu (viết liền không có dấu ngăn cách) các giá trị tham số theo thứ tự đã sắp xếp ở trên (giatri1 – giatri2 - …)
  • Tạo checksum bằng cách sử dụng phương pháp mã hóa HMAC với giải thuật SHA1 trên dữ liệu được tạo ra ở bước trên và khóa bí mật giữa 2 bên
Dữ liệu trả về

  Tên trường

Kiểu dữ liệu

Bắt buộc

Mô tả
 order_id
String(45)
 Y 
Mã hóa đơn thanh toán submit lên baokim.vn
transaction_id
String(13)
 Y 
Mã giao dịch thanh toán trên baokim.vn
created_on
Integer
 Y 
Thời điểm tạo giao dịch trên hệ thống baokim.vn. Tính bằng số giây kể từ thời điểm 1/1/1970 12:00 AM (ví dụ 1283220985 = 31-08-2010:16:25 AM)
payment_type
Integer
 Y 
Hình thức thanh toán: 1: thanh toán trực tiếp, 2: thanh toán an toàn
transaction_status
Integer
 Y 
Trạng thái giao dịch
total_amount
Double
Y
Tổng số tiền người mua thanh toán (có thể bao gồm thêm phí khi thanh toán qua internet banking, phí chuyển tiền…)
net_amount
Double
Y
Số tiền người bán thực nhận
fee_amount
Double
Y
Phí dịch vụ baokim thu
merchant_id
Integer
Y
Mã website tích hợp
customer_name
String(100)
Y
Tên người thanh toán
customer_email
String(45)
Y
Email người thanh toán
customer_phone
String(45)
Y
Số điện thoại người thanh toán
customer_address
String(255)
N
Địa chỉ người thanh toán
Checksum
String(32)
Y
Chuỗi bảo mật tránh giả mạo thông tin (cách thức tạo ghi ở bên dưới)

# Các bược tích hợp

# Các bước tích hợp sử dụng ngôn ngữ PHP

Truy cập vào địa chỉ Đăng ký tích hợp Website để đăng ký tích hợp website, sau đó các bạn truy cập vào địa chỉ Đăng ký tài khoản Pro và làm theo các bước sau:

# Đăng ký tài khoản tích hợp Pro

Thông tin bắt buộc bao gồm:

# Lấy thông tin tích hợp

Để có thể tiến hành tích hợp phương thức thanh toán Pro các bạn cần có những thông tin sau:

  • Email tài khoản người bán(EMAIL_BUSINESS)
    (Là email tài khoản Bảo Kim đăng ký tích hợp website)
  • Mã website(MERCHANT_ID)
  • Mật khẩu website(SECURE_PASS)
    (Được hiển thị một lần khi đăng ký thành công)
  • Tài khoản API Username
  • Tài khoản API Password
  • Public key
  • Private key

Để lấy Mã website, Tài khoản API UsernameAPI Password xin vui lòng truy cập Tại đây

Hướng đẫn tạo Public Key và Private Key:

  1. Download openssl
  2. Mở cmd và cd đến thư mục openssl/bin (vd C:\openssl-0.9.8k_X64\bin)
  3. Thực hiện 3 bước dưới đây trong cmd để generate rsa public/private key (chú ý thay các tham số trong mục -subj cho phù hợp với từng merchant).
    #SET ENV
    set OPENSSL_CONF=C:\openssl-0.9.8k_X64\openssl.cnf
    #GEN CSR & PRIVATE KEY
    openssl req -new -newkey rsa:2048 -nodes -sha256 -out server.csr -keyout server.key -subj "/C=vn/ST=Hanoi/L=Hanoi/O=ORGANIZATION/OU=DEPARTMENT/CN=www.example.com"
    #GEN PUBLIC KEY
    openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt
# Tải thư viện và tiến hành tích hợp

Tiến hành tích hợp các bạn mở file constants.php trong thư viện tải về và điền các thông tin sau:

  • EMAIL_BUSINESS (Là địa chỉ email khi các bạn đăng ký tài khoản Pro)
  • MERCHANT_ID (Là mã website)
  • SECURE_PASS (Là mật khẩu website)
  • API_USER (Là tài khoản API Username)
  • API_PWD (Là tài khoản API Password)
  • PRIVATE_KEY_BAOKIM (Xem hướng dẫn tạo PrivateKey )

Sau khi điền các thông tin trên các bạn đã có thể thanh toán qua Bảo Kim sử dụng phương thức thanh toán Pro.

# Các bước tích hợp sử dụng ngôn ngữ ASP.NET

# Đăng ký tích hợp website

Để đăng ký tích hợp website các bạn truy cập vào địa chỉ sau: Đăng ký tích hợp Website

Lưu ý: khi khách hàng đăng ký tích hợp website thành công mật khẩu website(secure_code) sẽ được hiển thị trên popup các bạn cần luu lại thông tin này vì nó chỉ được cung cấp một lần trên hệ thống
# Lấy thông tin tích hợp

Bảo Kim cung cấp cho khách hàng Mã website, Tài khoản API UsernameAPI Password.
Xin vui lòng truy cập Tại đây.

# Tải thư viện và tiến hành tích hợp

Tiến hành tích hợp các bạn mở file App_Code/SessionKey.cs trong thư viện tải về và điền các thông tin sau:

  • EMAIL_BUSINESS (Là địa chỉ email khi các bạn đăng ký tài khoản Bảo Kim)
  • MERCHANT_ID (Là mã website)
  • SECURE_PASS (Là mã mật khẩu website)
  • API_USER (Là tài khoản API Username)
  • API_PWD (Là tài khoản API Password)

Sau khi điền các thông tin trên các bạn đã có thể thanh toán qua Bảo Kim sử dụng phương thức thanh toán Pro.

# Các bước tích hợp sử dụng ngôn ngữ Java

# Đăng ký tích hợp website

Để đăng ký tích hợp website các bạn truy cập vào địa chỉ sau: Đăng ký tích hợp Website

Lưu ý: khi khách hàng đăng ký tích hợp website thành công mật khẩu website(secure_code) sẽ được hiển thị trên popup các bạn cần luu lại thông tin này vì nó chỉ được cung cấp một lần trên hệ thống
# Lấy thông tin tích hợp

Bảo Kim cung cấp cho khách hàng Mã website, Tài khoản API UsernameAPI Password.
Xin vui lòng truy cập Tại đây.

# Tải thư viện và tiến hành tích hợp

Tiến hành tích hợp các bạn mở file BaoKimPayment.java trong thư viện tải về và điền các thông tin sau:

  • MERCHANT_ID (Là mã website)
  • SECURE_PASS (Là mã mật khẩu website)

Sau khi điền các thông tin trên các bạn đã có thể thanh toán qua Bảo Kim sử dụng phương thức thanh toán Pro.

Tích hợp miễn phí ngay

Kỹ thuật

    3
  • Trần Bảo Trung
  • 0987627790

Kinh doanh

    1
  • Nguyễn Phương Dung
  • 0973132671
    2
  • Nguyễn Đăng Hiếu
  • 0979303590
    3
  • Lê Quỳnh Trang
  • 0982697992