Tài liệu hướng dẫn tích hợp BPN u hướng dẫn tích hợp BPN ng dẫn tích hợp BPN n tích hợp BPN p BPN Cổng toán trực tuyến Bảo Kimng toán trực tuyến Bảo Kimc tuyến Bảo Kimn Bảo Kimo Kim Người lập: Nguyễn Minh Khôi (khoinm@baokim.vn) Ngày lập: Phiên bản: 24/09/2010 1.0 Giớng dẫn tích hợp BPN i thiệu hướng dẫn tích hợp BPN u BPN Baokim Payment Notification (BPN) dịch vụ gửi thông báo liên quan đến giao dịch tốn hóa đơn cổng toán trực tuyến Bảo Kim Bạn sử dụng BPN để tự động hóa quy trình nghiệp vụ (tự động hồn thành đơn hàng, cung cấp nội dung số, kích hoạt tài khoản ) Các thông tin trả qua BPN bao gồm trạng thái giao dịch thơng tin tố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 BPN sử dụng cho giao dịch toán đơn hàng Các giao dịch toán sản phẩm qun góp (tích hợp đơn giản) khơng sử dụng tính Các trạng thái giao dịch cập nhật qua hệ thống BPN có thao tác: Tạo giao dịch Xác minh OTP Duyệt phiếu thu (đối với 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 chờ hết hạn tạm giữ) Từ chối nhận tiền (giao dịch bị hủy) Từ chối toán (giao dịch bị hủy) Thanh tốn (hồ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 thực từ phía người dùng hệ thống từ phía quản trị Baokim (đối với thao tác duyệt phiếu thu, đóng băng, hủy đóng băng giao dịch) Mơ tảo Kim giao tiến Bảo Kimp BPN Baokim website tích hợpa Baokim website tích h ợp BPN p Quy trình gửi tin BPN thực qua bước sau: Baokim gửi tin BPN đến BPNListener website tích hợp BPNListener tiến hành xác minh thông tin cách gửi trả lại thông tin Baokim, thơng tin phải xác thứ tự tin gốc từ Baokim đẩy sang Baokim tiến hành xác minh tin đó, trả VERIFIED Baokim gửi tin đến website merchant, INVALID khơng phải Baokim gửi tin tin bị hết hạn xử lý Cơ chế xác minh tránh thông tin giả mạo đẩy đến BPN Listener giúp Baokim xác nhận website tích hợp nhận BPN, giúp tạo chế gửi lại Sau thực xong bước xác minh thông tin, kết trả từ Baokim VERIFIED website tích hợp tiếp tục xử lý quy trình nghiệp vụ tùy theo trạng thái giao dịch trả Các quy trình nghiệp vụ kích hoạt tài khoản, dịch vụ, gửi link download media Ví dụ mẫu tin BPN gửi phía website tích hợp: mẫn tích hợp BPN u tin BPN gửi phía website tích hợp: bảo Kimn tin BPN gửi phía website tích hợp:i tin BPN gửi phía website tích hợp: phía website tích hợp BPN p: created_on=1287729470&customer_address=Dia+Chi+Khach+Hang&customer_email=khoin m %40baokim.vn&customer_name=Nguyen+Minh+Khoi&customer_phone=84987654321&fee_amo unt=1000&merchant_address=Dia+Chi+Cong+Ty&merchant_email=hangntt %40baokim.vn&merchant_id=8&merchant_name=Nguyen+Thi+Thu+Hang&merchant_phone=84 981234567&net_amount=99000&order_id=100139&payment_type=2&total_amount=100000 00&transaction_id=2506B4F7E6E6C&transaction_status=4&resend=true&verify_sign=2 IsQX54QVnYrU2wpsaWJCusC1veXr0vu2auZ451trdoA6 Mô tả ý nghĩa trường thông tin: Trường order_id transaction_id created_on Kiểu String(45) String(13) Integer Bắt buộc Y Y Y payment_type Integer Y Mơ tả Mã hóa đơn tốn submit lên baokim.vn Mã giao dịch toán baokim.vn Thời điểm tạo giao dịch hệ thống baokim.vn Tính 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) Hình thức toán: transaction_status Integer Y total_amount Double Y net_amount fee_amount merchant_id customer_name customer_email customer_phone customer_address verify_sign resend Double Double Integer String(100) String(45) String(45) String(255) String(45) Boolean Y Y Y Y Y Y N Y N 1: toán trực tiếp 2: tốn an tồn 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 3: giao dịch chờ Bảo Kim duyệt 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 9: giao dịch hoàn tiền 10: giao dịch yêu cầu chuyển tiền 11: giao dịch hoàn tiền phần 12: giao dịch bị đóng băng 13: giao dịch bị tạm giữ (thanh tốn an tồn) 14: giao dịch khơng xác định 15: giao dịch bị hủy Tổng số tiền người mua toán (có thể bao gồm thêm phí tốn qua internet banking, phí chuyển tiền ) Số tiền người bán thực nhận Phí dịch vụ baokim thu Mã website tích hợp Tên người toán Email người toán Số điện thoại người toán Địa người toán Mã bảo mật để xác minh thơng tin phía Baokim Xác định tin nhắn BPN có phải gửi lại hay không Thực tuyến Bảo Kimc thi BPNListener website tích hợp BPN p BPN Listener thực lắng nghe website tích hợp để tiếp nhận tin BPN gửi đến từ Baokim Một BPN Listener phải đảm bảo yêu cầu sau: Chờ request HTTP Post từ Baokim Tạo request HTTP Post ngược lại Baokim xác thơng tin nhận giá trị lẫn thứ tự gửi đến https://www.baokim.vn/bpn/verify http://sandbox.baokim.vn/bpn/verify Chờ kết trả từ Baokim VERIFIED INVALID Xác nhận HTTP Response Code trả 200 (OK) Nếu kết trả VERIFIED tiến hành: o Kiểm tra trạng thái giao dịch, thơng thường hồn thành đơn hàng trạng thái giao dịch thành công o Sử dụng mã giao dịch (transaction_id) để xác nhận giao dịch chưa gắn với đơn hàng thành công nào, tránh xử lý trùng lặp o Kiểm tra mã hóa đơn để xác nhận thơng tin đơn hàng o Kiểm tra email người nhận toán email website tích hợp đăng ký với Baokim Tiến hành xác minh thêm thông tin phụ: giá, mô tả để tránh gian lận giao dịch Nếu kết trả INVALID HTTP Response Code khác 200: tiến hành ghi log để truy vết o Thông thường BPN Listener form nhận thông tin viết ngơn ngữ lập trình web (bpnlistener.php, bpnlistener.aspx, bpnlistener.jsp ) Code mẫu bạn tải https://www.baokim.vn/faq/category/tich-hop-gio-hang-website 4 Cơ chế xử lý BPN chến Bảo Kim xửi phía website tích hợp: lý BPN tin BPN coi hợp lệ thỏa mãn điều kiện sau: Nội dung thông tin Baokim nhận để xác minh phải giống nội dung Baokim gửi sang website tích hợp giá trị thứ tự trường thông tin Thời gian từ Baokim gửi tin đến Baokim nhận yêu cầu xác minh phải nhỏ 30 giây Khi tin BPN gửi mà khơng có phản hồi phản hồi Baokim không xác minh thơng tin tin gửi lại sang website tích hợp Cơ chế gửi lại sau: o Thơng tin gửi lại vịng ngày o Khoảng cách lần gửi tin BPN ngày 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 nhận thông tin gửi đến nên tiến hành xác minh trước thực quy trình nghiệp vụ khác ... Mô tảo Kim giao tiến Bảo Kimp BPN Baokim website tích hợpa Baokim website tích h ợp BPN p Quy trình gửi tin BPN thực qua bước sau: Baokim gửi tin BPN đến BPNListener website tích hợp BPNListener... hoạt tài khoản, dịch vụ, gửi link download media Ví dụ mẫu tin BPN gửi phía website tích hợp: mẫn tích hợp BPN u tin BPN gửi phía website tích hợp: bảo Kimn tin BPN gửi phía website tích hợp: i... hay không Thực tuyến Bảo Kimc thi BPNListener website tích hợp BPN p BPN Listener thực lắng nghe website tích hợp để tiếp nhận tin BPN gửi đến từ Baokim Một BPN Listener phải đảm bảo yêu cầu sau: