III. Giải pháp tích hợp chi hộ
1. Giải Pháp API Chi Hộ
1.1. Giới thiệu:
Merchant có thể tạo lệnh chi tiền từ nguồn là số dư merchant/ ví doanh nghiệp đến ví PayME/tài khoản ngân hàng/thẻ ATM. Dịch vụ chi hộ cung cấp giải pháp chi tiền đơn giản, nhanh chóng, nhận tiền tức thời 24/7. Lịch sử giao dịch sẽ được lưu lại, đảm bảo tra cứu hiệu quả, an toàn và bảo mật. Để có thể sử dụng nguồn tiền phải có mã xác nhận chi theo cấu hình của nguồn chi, nếu không có xác nhân chi nguồn chi phải xác nhận từng giao dịch qua link yêu cầu xác nhận để an toàn nguồn tiền cho Merchant.
1.2. Sơ đồ tích hợp:
| Bước | Tên bước | Diễn giải | Thực hiện |
|---|---|---|---|
| 1. | Request a money transfer | Merchant Owner thực hiện tạo lệnh yêu cầu chi | Merchant Owner |
| 2. | Create a money transfer order | Merchant Server kết nối đến PayME Server khởi tạo yêu cầu chi | Merchant |
| 3. | Authentication required? | Nếu yêu cầu Merchant cài đặt yêu cầu xác thực khi chi, PayME sẽ trả về verifyLink. Nếu không cần xác thực sẽ đến bước 7 | PayME |
| 4. | Merchant client opens verifyLink | Merchant Client mở verifyLink của PayME trả về | Merchant |
| 5. | Enter verifyCode at verifyLink | Merchant Owner nhập verifyCode là OTP hoặc mật khẩu giao dịch để xác nhận đồng ý chi ở verifyLink | Merchant Owner |
| 6. | Confirm transfer agreement | Merchant Owner bấm đồng ý để tiến hành chi | Merchant Owner |
| 7. | Make money transfer | Nếu verifyCode hợp lệ, PayME sẽ tiến hành chi đến tài khoản nhận ở lệnh yêu cầu chi | PayME |
| 8. | Return transaction results | PayME xử lý giao dịch chi và IPN đến Server Merchant để ghi nhân kết quả giao dịch chi | PayME |
| 9. | Show order results | Merchant hiển thị kết quả giao dịch chi | Merchant |
1.3. Danh sách API tích hợp
| Tên API | Endpoint | Hướng gọi | Mô tả |
|---|---|---|---|
| Tạo yêu cầu chi | pobo/transfer | MC->PayME | Sử dụng tạo yêu cầu chi |
| Callback | ipn url mc | PayME->MC | PayME gọi lại Merchant thông báo kết quả |
| Truy vấn lệnh chi | pobo/query | MC->PayME | Merchant chủ động truy vấn kết quả lệnh chi |
| Thực hiện lại lệnh chi | pobo/retry | MC->PayME | Thực hiện chi lệnh yêu cầu |
| Hủy lệnh chi | pobo/cancel | MC->PayME | Hủy lệnh chi |
1.4. Hướng dẫn tích hợp
Ở Merchant Client cho phép lập yêu cầu chi để xác định số tiền cần chi và tài khoản nhận.
Sau khi Merchant Owner đồng ý chi Merchant Client gửi thông tin đến Merchant Server, Merchant Server gửi yêu cầu tạo yêu cầu chi đến api pobo/transfer của PayME Server để tạo đơn thanh toán. Nếu nguồn chi sử dụng chứng thực là google authen hoặc token có thể gửi kèm ở tham số verifyCode để xác thực chi ngay.
Trong trường hợp PayME có trả về verifyLink, Merchant Client mở verifyLink do PayME trả về để khách hàng thực hiện nhập verifyCode .Trường hợp Merchant không đủ số dư thực hiện lệnh chi có thể trực tiếp tực hiện nạp thêm từ verifyLink.
PayME Server callback IPN đến Merchant Server
Nếu verifyCode hợp lệ sẽ tiến hành thực hiện lệnh chi và (callback/notify) thông tin kết quả chi đến Merchant Server theo ipnUrl đã gửi sang lúc yêu cầu chi.
Nếu quá thời gian cho phép nhưng chưa có kết quả callback ipn đến merchant server có thể chủ động gọi api pobo/query để kiểm tra trạng thái lệnh chi.
Thực hiện lại lệnh chi thất bại
Với các lênh chi thất bại do lỗi trong quá trình chi merchant có thể yêu cầu thực hiện lại lệnh chi bằng cách chủ động gọi api pobo/retry.
Với các lênh chi thất bại hoặc lệnh chi chưa nhập verifyCode merchant có thể yêu cầu hủy lệnh chi bằng cách chủ động gọi api pobo/cancel.