Pay2S Partner API – Khái niệm

Nội dung Markdown đầy đủ của trang tài liệu.

# 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](./hosted-link.md) để 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](./webhook-events.md). 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](./bank.md) và [hướng dẫn webhook](./webhook.md) để 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:

```mermaid
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](https://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](./authentication.md).
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](./bank.md).
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](./webhook.md).
7. Theo dõi hoạt động tích hợp qua [Analytics](./analytics.md) 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](./authentication.md).

## 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](./authentication.md) |
| Bank Subscription | Quản lý tài khoản ngân hàng | `/v1/banks` | [Ngân hàng](./bank.md) |
| Webhook | Quản lý thông báo giao dịch | `/v1/webhooks` | [Webhook](./webhook.md) |
| Analytics / Metrics | Thống kê và lịch sử gọi API | `/v1/metrics/*` | [Analytics](./analytics.md) |

Có thể dùng [Postman Collection](./postman.md) để 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ả. |