Tài liệu hướng dẫn tích hợp BPN
Cổng thanh toán trực tuyến Bảo Kim

1.     Giới thiệu BPN

Baokim Payment Notification (BPN) là một dịch vụ gửi thông báo liên quan đến các giao dịch thanh toán hóa đơn trên cổng thanh toán trực tuyến Bảo Kim. Bạn có thể sử dụng BPN để tự động hóa các quy trình nghiệp vụ (tự động hoàn thành đơn hàng, cung cấp các nội dung số, kích hoạt tài khoản...). Các thông tin trả về qua BPN bao gồm trạng thái giao dịch và các thông tin thanh toán khác (thông tin người mua, thông tin người bán, thông tin merchant tích hợp, mã giao dịch...).

Hiện tại BPN chỉ được sử dụng cho các giao dịch thanh toán đơn hàng. Các giao dịch thanh toán sản phẩm và quyên góp (tích hợp đơn giản) sẽ không sử dụng được tính năng này. Các trạng thái giao dịch được cập nhật qua hệ thống BPN khi có các thao tác:

  • Tạo giao dịch
  • Xác minh OTP
  • Duyệt phiếu thu (đối với thanh toán qua thẻ quốc tế)
  • Đồng ý nhận tiền (giao dịch chuyển sang trạng thái hoàn thành hoặc chờ hết hạn tạm giữ)
  • Từ chối nhận tiền (giao dịch bị hủy)
  • Từ chối thanh toán (giao dịch bị hủy)
  • Thanh toán ngay (hoàn thành giao dịch)
  • Đóng băng / hủy đóng băng giao dịch (giao dịch nghi vấn)

Các thao tác trên có thể được thực hiện từ phía người dùng hệ thống hoặc từ phía quản trị Baokim (đối với các thao tác duyệt phiếu thu, đóng băng, hủy đóng băng giao dịch).

 

 

2.     Mô tả giao tiếp BPN giữa Baokim và website tích hợp

 

Quy trình gửi tin BPN được thực hiện qua các bước như sau:

  1. Baokim gửi bản tin BPN đến BPNListener trên website tích hợp
  2. BPNListener tiến hành xác minh thông tin bằng cách gửi trả lại thông tin đó về Baokim, các thông tin này phải chính xác và đúng thứ tự như bản tin gốc từ Baokim đẩy sang.
  3. Baokim sẽ tiến hành xác minh bản tin đó, trả về VERIFIED nếu đúng là Baokim gửi bản tin đó đến website merchant, INVALID nếu không phải Baokim gửi bản tin đó hoặc bản tin bị hết hạn xử lý.

Cơ chế xác minh như trên sẽ tránh được các thông tin giả mạo đẩy đến BPN Listener và cũng giúp Baokim xác nhận website tích hợp đã nhận được BPN, giúp tạo ra cơ chế gửi lại.

Sau khi thực hiện xong các bước xác minh thông tin, nếu kết quả trả về từ Baokim là VERIFIED thì website tích hợp có thể tiếp tục xử lý quy trình nghiệp vụ tùy theo trạng thái giao dịch trả về. Các quy trình nghiệp vụ này có thể là kích hoạt tài khoản, dịch vụ, gửi link download media...

Ví dụ mẫu về 1 bản tin BPN gửi về phía website tích hợp:

created_on=1287729470&customer_address=Dia+Chi+Khach+Hang&customer_email=khoinm%40

baokim.vn&customer_name=Nguyen+Minh+Khoi&customer_phone=84987654321&fee_amount=100

0&merchant_address=Dia+Chi+Cong+Ty&merchant_email=hangntt%40baokim.vn&merchant_id=8&

merchant_name=Nguyen+Thi+Thu+Hang&merchant_phone=84981234567&net_amount=99000&ord

er_id=100139&payment_type=2&total_amount=100000.00&transaction_id=2506B4F7E6E6C&transac

tion_status=4&resend=true&verify_sign=2IsQX54QVnYrU2wpsaWJCusC1veXr0vu2auZ451trdoA6

Mô tả ý nghĩa các trường thông tin:

Trường

Kiể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 09:16:25 AM)

payment_type

Integer

Y

Hình thức thanh toán:

1: thanh toán ngay

2: thanh toán an toàn

transaction_status

Integer

Y

Trạng thái giao dịch:

1: giao dịch chưa xác minh OTP

2: giao dịch đã xác minh OTP

4: giao dịch hoàn thành

5: giao dịch bị hủy

6: giao dịch bị từ chối nhận tiền

7: giao dịch hết hạn

8: giao dịch thất bại

12: giao dịch bị đóng băng

13: giao dịch bị tạm giữ (thanh toán an toàn)

15: giao dịch bị hủy khi chưa xác minh OTP

X: các trạng thái giao dịch khác

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

verify_sign

String(45)

Y

Mã bảo mật để xác minh thông tin phía Baokim

resend

Boolean

N

Xác định tin nhắn BPN có phải được gửi lại hay không.

3.     Thực thi BPNListener trên website tích hợp

BPN Listener thực hiện lắng nghe trên website tích hợp để có thể tiếp nhận bản tin BPN gửi đến từ Baokim. Một BPN Listener phải đảm bảo được các yêu cầu sau:

  • Chờ request HTTP Post từ Baokim
  • Tạo request HTTP Post ngược lại Baokim chính xác các thông tin nhận được cả về giá trị lẫn thứ tự gửi đến https://www.baokim.vn/bpn/verify hoặc https://sandbox.baokim.vn/bpn/verify
  • Chờ kết quả trả về từ Baokim là VERIFIED hoặc INVALID
  • Xác nhận HTTP Response Code trả về là 200 (OK)
  • Nếu kết quả trả về là VERIFIED thì tiến hành:
    • Kiểm tra trạng thái giao dịch, thông thường chỉ hoàn thành đơn hàng
    • khi trạng thái giao dịch là thành công.
    • Sử dụng mã giao dịch (transaction_id) để xác nhận là giao dịch này chưa gắn với 1 đơn hàng thành công nào, tránh xử lý trùng lặp.
    • Kiểm tra mã hóa đơn để xác nhận thông tin đơn hàng
    • Kiểm tra email người nhận thanh toán là email của website tích hợp đăng ký với Baokim
    • Tiến hành xác minh thêm các thông tin phụ: giá, mô tả... để tránh các gian lận trong giao dịch
  • Nếu kết quả trả về là INVALID hoặc HTTP Response Code khác 200: tiến hành ghi log để truy vết.

Thông thường BPN Listener sẽ là 1 form nhận thông tin viết bằng các ngôn ngữ lập trình web (bpnlistener.php, bpnlistener.aspx, bpnlistener.jsp...). Code mẫu bạn có thể tải về tại https://www.baokim.vn/developers/framework/download?id=6.

4.     Cơ chế xử lý BPN

1 bản tin BPN được coi là hợp lệ nếu thỏa mãn các điều kiện sau:

  • Nội dung thông tin Baokim nhận được để xác minh phải giống nội dung Baokim gửi sang website tích hợp cả về giá trị và thứ tự các trường thông tin
  • Thời gian từ khi Baokim gửi tin đến khi Baokim nhận được yêu cầu xác minh phải nhỏ hơn 30 giây.
  • Khi một bản tin BPN gửi đi mà không có phản hồi hoặc phản hồi nhưng Baokim không xác minh được thông tin thì bản tin đó sẽ được gửi lại sang website tích hợp. Cơ chế gửi lại như sau:
    • Thông tin sẽ được gửi lại trong vòng 4 ngày
    • Khoảng cách giữa 2 lần gửi tin BPN sẽ càng ngày càng lớn tùy theo số lần gửi lại.

Để tránh tình trạng hết hạn xác minh, BPN Listener khi nhận được thông tin gửi đến nên tiến hành xác minh ngay trước khi thực hiện các quy trình nghiệp vụ khác.

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

Kỹ thuật

    4
  • Hỗ Trợ Kỹ Thuật
  • 0988404580

Kinh doanh

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