🔗 Pay2S Partner API – Khái niệm

Tài liệu này dành cho đối tác tích hợp hệ thống với nền tảng Pay2S thông qua API.
Mục tiêu của bộ API là giúp đối tác:

Kết nối tài khoản ngân hàng (Bank Subscription)
Nhận thông báo giao dịch theo thời gian thực (Webhook)
Theo dõi và phân tích hoạt động (Analytics)
Quản lý quyền truy cập và xác thực (Authentication)

🌐 Tổng quan hệ thống

Pay2S Partner API hoạt động độc lập với hệ thống người dùng thông thường của Pay2S.vn,
được thiết kế dành riêng cho merchant, đối tác fintech, website trung gian thanh toán, hoặc hệ thống nội bộ doanh nghiệp muốn:

Tự động đồng bộ giao dịch IN/OUT theo thời gian thực
Gắn kết tài khoản ngân hàng của mình với nền tảng Pay2S
Tạo webhook callback nhận thông báo và xử lý logic riêng

🧩 Kiến trúc tổng quan

mermaid

graph TD
A[Merchant / Đối tác] -- API Request --> B(Pay2S Partner Gateway)
B -- Xác thực Access Key / Secret Key --> C[Authentication Service]
B -- Kết nối ngân hàng --> D[Bank API (ACB, BIDV, VCB, ...)]
B -- Gửi callback --> E[Webhook Endpoint của Merchant]
B --> F[Metrics & Analytics Dashboard]

Luồng chính:

Đối tác đăng nhập Pay2S.vn → vào mục Partner API để lấy Access Key và Secret Key
Dùng Basic Auth (Authorization: Basic base64(access:secret)) để cấp Bearer Token tạm thời
Dùng Token đó để gọi các API như /v1/banks, /v1/webhooks, /v1/metrics, v.v.

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

Thành phần	Mô tả
Access Key	Mã định danh cho đối tác (giống Client ID)
Secret Key	Khóa bí mật dùng để cấp token
Bearer Token	Token tạm thời dùng khi gọi API (hết hạn sau 3600s)
Signature (tuỳ chọn)	Chữ ký mã hoá HMAC (với secret key) cho các giao dịch đặc biệt)

Gợi ý

Hệ thống hiện hỗ trợ Basic Auth → Bearer Token, giúp đơn giản hóa quá trình xác thực, không cần sinh chữ ký phức tạp.

⚙️ Các nhóm API chính

Nhóm API	Mục đích	Đường dẫn
Authentication	Cấp và xác thực token	`/v1/auth/authorize`
Bank Subscription	Quản lý tài khoản ngân hàng	`/v1/banks`
Webhook	Quản lý callback giao dịch	`/v1/webhooks`
Analytics / Metrics	Theo dõi log & thống kê	`/v1/metrics`

🧠 Một số thuật ngữ

Thuật ngữ	Giải thích
Webhook	Endpoint do đối tác đăng ký để Pay2S gửi thông báo giao dịch
Transaction IN/OUT	Giao dịch tiền vào (IN) hoặc tiền ra (OUT) từ tài khoản
VA Number	Số tài khoản ảo định danh chủ tài khoản
Plan	Gói dịch vụ của user, quy định số lượng bank hoặc webhook tối đa
Metrics	Dữ liệu thống kê log gọi API, tốc độ phản hồi, trạng thái, IP, thời gian

🔗 Pay2S Partner API – Khái niệm ​

🌐 Tổng quan hệ thống ​

🧩 Kiến trúc tổng quan ​

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