Pay2S Partner API – Khái niệm

Pay2S Partner API giúp đối tác tích hợp quản lý tài khoản ngân hàng và nhận thông báo giao dịch vào hệ thống của mình. Tài liệu này giới thiệu các thành phần và thứ tự tích hợp trước khi đi vào từng API.

Liên kết bằng form Pay2S

Dùng Hosted Link & SDK để khách nhập thông tin và xác thực trên form Pay2S. Backend tạo phiên, frontend mở form, backend nhận kết quả qua Webhook sự kiện. Hai nhóm sự kiện tiến trình và trạng thái tài khoản có thể dùng chung một URL nhận.

Tổng quan

Các nhóm chức năng chính gồm:

• Ngân hàng: liên kết tài khoản, xác nhận OTP, xem danh sách, bật/tắt và xoá liên kết.
• Webhook: đăng ký URL nhận thông báo giao dịch và quản lý webhook của từng tài khoản ngân hàng.
• Analytics: xem thống kê và lịch sử gọi API.
• Xác thực: dùng Access Key và Secret Key để lấy Bearer Token gọi API.

Phương thức liên kết và bước xác minh phụ thuộc vào ngân hàng, loại tài khoản. Webhook cho phép chọn giao dịch vào (IN), ra (OUT) hoặc cả hai (ALL); dữ liệu nhận được phụ thuộc vào kết nối ngân hàng và cấu hình webhook. Xem quản lý tài khoản ngân hàng và hướng dẫn webhook để biết chi tiết.

Base URL: https://api-partner.pay2s.vn

Các thành phần và hướng trao đổi

Sơ đồ dưới đây mô tả các kết nối khi tích hợp:

flowchart LR
    A["Hệ thống đối tác"] -->|"Basic Auth: lấy token"| B["API xác thực"]
    B -->|"Bearer Token"| A
    A -->|"Bearer Token: gọi API"| C["Pay2S Partner API"]
    C -->|"Liên kết tài khoản"| D["Ngân hàng"]
    C -->|"Thông báo giao dịch kèm webhook token"| E["URL nhận webhook của đối tác"]

Quy trình tích hợp

1. Đăng nhập merchant.pay2s.vn → Bankhub → thiết lập để lấy Access Key và Secret Key.
2. Gọi POST /v1/auth/authorize với Authorization: Basic base64(access_key:secret_key) để lấy Bearer Token. Xem xác thực đối tác.
3. Dùng Authorization: Bearer <access_token> để gọi POST /v1/banks và liên kết tài khoản ngân hàng. Nếu API yêu cầu OTP, thực hiện bước xác nhận tương ứng trong hướng dẫn ngân hàng.
4. Gọi GET /v1/banks để kiểm tra trạng thái liên kết và lấy id của tài khoản ngân hàng. Đây là ID bản ghi, không phải số tài khoản.
5. Gọi POST /v1/webhooks, truyền id vừa lấy vào user_bank_id, cùng webhook_url và loại giao dịch cần nhận (IN, OUT hoặc ALL). Lưu token riêng được cấp cho webhook.
6. Tại URL nhận webhook, kiểm tra Authorization: Bearer <webhook_token>, xử lý thông báo và trả phản hồi theo hướng dẫn webhook.
7. Theo dõi hoạt động tích hợp qua Analytics và lịch sử gửi webhook.

Thành phần xác thực

Bearer Token gọi API và webhook token phục vụ hai hướng kết nối khác nhau. Dùng đúng token cho từng hướng; khi Bearer Token gọi API hết hạn, lấy token mới theo hướng dẫn xác thực.

Các nhóm API chính

Các đường dẫn dưới đây dùng với Base URL ở đầu trang. /v1/metrics/* biểu thị nhóm endpoint thống kê; chọn endpoint cụ thể trong trang Analytics.

Có thể dùng Postman Collection để tham khảo request và thử tích hợp.

Thuật ngữ