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.

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

Thành phần	Mục đích
Access Key	Định danh đối tác khi yêu cầu cấp token.
Secret Key	Dùng cùng Access Key trong Basic Auth để lấy Bearer Token.
Bearer Token gọi API	Đối tác gửi đến Pay2S trong header Authorization để gọi các API ngân hàng, webhook và thống kê. Thời hạn được trả về qua expires_in; mẫu xác thực hiện dùng 3600 giây.
Webhook token	Token riêng của webhook. Pay2S gửi token này đến URL nhận webhook của đối tác trong header Authorization: Bearer <webhook_token>.

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.

Nhóm API	Mục đích	Đường dẫn	Tài liệu
Authentication	Cấp Bearer Token	/v1/auth/authorize	Xác thực
Bank Subscription	Quản lý tài khoản ngân hàng	/v1/banks	Ngân hàng
Webhook	Quản lý thông báo giao dịch	/v1/webhooks	Webhook
Analytics / Metrics	Thống kê và lịch sử gọi API	/v1/metrics/*	Analytics

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

Thuật ngữ

Thuật ngữ	Giải thích
Bank Subscription	Liên kết tài khoản ngân hàng với Pay2S.
Webhook	Cơ chế Pay2S gửi thông báo giao dịch đến URL do đối tác đăng ký.
IN / OUT / ALL	Giao dịch tiền vào / tiền ra / cả hai loại.
VA Number	Số tài khoản ảo (Virtual Account); sử dụng giá trị vaNumber API trả về khi có.
user_bank_id	ID tài khoản ngân hàng trên Pay2S, lấy từ trường id trong danh sách tài khoản để gắn webhook.
Metrics	Số liệu thống kê hoạt động API, như số lượt gọi, thời gian phản hồi và trạng thái kết quả.