<!-- pay2s-offline-docs-v1 -->
# Tài liệu Pay2S đính kèm

Ngày chụp nội dung tài liệu: 2026-09-29 (UTC).
Nguồn: https://docs.pay2s.vn/

Đây là bản tài liệu lưu tại ngày trên, không tự cập nhật sau khi tải. Nội dung các trang được chép đầy đủ bên dưới; không cần mở link để đọc. Các liên kết khác là nguồn tham khảo bổ sung. Nếu thiếu thông tin cần thiết, hãy hỏi người dùng thay vì tự đoán.

## Mục lục
- 📊 Analytics / Thống kê API
- 🔐 Authentication / Xác thực đối tác
- 🏦 Bank Subscription / Quản lý ngân hàng (theo Postman Collection)
- 🔗 Pay2S Partner API – Khái niệm
- 📦 Postman Collection – Pay2S Partner API
- 🔔 Webhook / Thông báo giao dịch tự động

---

Nguồn trang: https://docs.pay2s.vn/partner/analytics.html

# 📊 Analytics / Thống kê API

## 🧭 Giới thiệu

API **Analytics** cung cấp khả năng theo dõi và thống kê chi tiết về các hoạt động tích hợp giữa **đối tác (Partner)** và hệ thống **Pay2S**.  
Qua đó, bạn có thể giám sát lưu lượng gọi API, thời gian phản hồi trung bình, tỷ lệ thành công/thất bại, và theo dõi hiệu năng dịch vụ.

---

## 🔐 Header chung

```
Authorization: Bearer <token>
Content-Type: application/json
```

> Token được cấp thông qua API `/v1/admin/authorize/issue` (hạn sử dụng mặc định 3600 giây).

---

## 1️⃣ Thống kê tổng quan API calls

**GET** `/v1/metrics/calls`

Trả về thông tin thống kê số lượng cuộc gọi API của đối tác theo ngày.

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": {
    "total_calls": 142,
    "success_calls": 136,
    "error_calls": 6,
    "average_response_ms": 215,
    "last_updated": "2025-10-14T13:20:00+07:00"
  }
}
```

### **Giải thích**
| Trường | Ý nghĩa |
|--------|----------|
| `total_calls` | Tổng số lần gọi API |
| `success_calls` | Số lần phản hồi thành công (HTTP 200) |
| `error_calls` | Số lần lỗi (HTTP 4xx/5xx) |
| `average_response_ms` | Thời gian phản hồi trung bình (ms) |
| `last_updated` | Thời điểm cập nhật gần nhất |

---

## 2️⃣ Biểu đồ chi tiết theo endpoint

**GET** `/v1/metrics/endpoints`

Dùng để xem chi tiết từng endpoint API, giúp bạn nhận biết các điểm nghẽn hiệu năng hoặc tần suất sử dụng cao.

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": [
    {
      "endpoint": "/v1/banks",
      "method": "GET",
      "calls": 85,
      "success": 82,
      "failed": 3,
      "average_ms": 130
    },
    {
      "endpoint": "/v1/webhooks",
      "method": "POST",
      "calls": 15,
      "success": 14,
      "failed": 1,
      "average_ms": 210
    }
  ]
}
```

### **Ý nghĩa**
| Trường | Mô tả |
|--------|--------|
| `endpoint` | Đường dẫn API |
| `method` | Loại HTTP method (GET, POST, DELETE, v.v.) |
| `calls` | Số lần gọi tổng cộng |
| `success` | Số lần thành công |
| `failed` | Số lần lỗi |
| `average_ms` | Thời gian phản hồi trung bình |

---

## 3️⃣ Thống kê theo ngày / tuần / tháng

**GET** `/v1/metrics/period?range=daily`

### **Tham số hỗ trợ**
| Tham số | Giá trị | Mô tả |
|----------|----------|--------|
| `range` | `daily` / `weekly` / `monthly` | Chọn phạm vi thống kê |

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": [
    { "date": "2025-10-10", "calls": 42, "average_ms": 190 },
    { "date": "2025-10-11", "calls": 55, "average_ms": 210 },
    { "date": "2025-10-12", "calls": 45, "average_ms": 230 }
  ]
}
```

---

## 4️⃣ Theo dõi tình trạng hệ thống

**GET** `/v1/metrics/status`

Kiểm tra tình trạng hoạt động của hệ thống API Pay2S (uptime, latency, trạng thái database).

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": {
    "uptime": "99.98%",
    "average_latency_ms": 185,
    "db_status": "OK",
    "api_gateway": "Operational",
    "last_check": "2025-10-14T13:30:00+07:00"
  }
}
```

---

## 5️⃣ Ghi log hoạt động API

**GET** `/v1/metrics/logs`

Trả về danh sách các lần gọi gần nhất của tài khoản đối tác (Partner API).

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": [
    {
      "id": 1001,
      "endpoint": "/v1/banks",
      "method": "GET",
      "response_ms": 132,
      "status_code": 200,
      "timestamp": "2025-10-14T13:12:03+07:00",
      "ip": "103.78.2.55"
    },
    {
      "id": 1002,
      "endpoint": "/v1/webhooks",
      "method": "POST",
      "response_ms": 254,
      "status_code": 500,
      "timestamp": "2025-10-14T13:13:05+07:00",
      "ip": "103.78.2.55"
    }
  ]
}
```

---

## 🧠 Lưu ý & Thực hành tốt

- Các endpoint `/metrics/*` chỉ khả dụng cho **Partner có token hợp lệ**.
- Số liệu được **cache 30–60 giây**, nên không phản ánh tức thời từng request.
- Khi response_ms = 0 → có thể do request nội bộ chưa log được thời gian phản hồi (hãy kiểm tra server clock).
- Dữ liệu này có thể dùng để vẽ biểu đồ monitor trên dashboard nội bộ.

---

## 🧪 cURL mẫu

### Lấy thống kê tổng quan
```bash
curl -X GET https://partner.pay2s.vn/v1/metrics/calls \
 -H "Authorization: Bearer <token>"
```

### Lấy danh sách log gần nhất
```bash
curl -X GET https://partner.pay2s.vn/v1/metrics/logs \
 -H "Authorization: Bearer <token>"
```

---

::: tip Gợi ý tích hợp
Bạn có thể tích hợp dữ liệu từ `/metrics` vào dashboard BI (như Grafana, Metabase, PowerBI) để theo dõi lưu lượng và hiệu năng API của chính bạn.
:::


---

Nguồn trang: https://docs.pay2s.vn/partner/authentication.html

# 🔐 Authentication / Xác thực đối tác

## 🧭 Giới thiệu

Hệ thống **Pay2S Partner API** sử dụng cơ chế xác thực hai tầng để đảm bảo an toàn cho các kết nối từ phía đối tác.

1. **Bước 1:** Đối tác đăng nhập vào [Pay2S.vn](https://pay2s.vn) để lấy **Access Key** và **Secret Key**.  
2. **Bước 2:** Sử dụng cặp khóa này để thực hiện **Basic Authentication**, lấy về **Bearer Token** tạm thời.  
3. **Bước 3:** Dùng **Bearer Token** này để gọi các API như `/v1/banks`, `/v1/webhooks`, `/v1/metrics`, v.v.

---

## 🧩 Luồng xác thực tổng quan

```mermaid
sequenceDiagram
    participant C as Client (Partner)
    participant G as Pay2S Partner Gateway
    participant A as Auth Service
    participant API as Protected API

    C->>G: POST /v1/auth/authorize (Basic Auth)
    G->>A: Xác minh Access Key / Secret Key
    A-->>G: Trả về Bearer Token (hiệu lực 3600s)
    G-->>C: 200 OK + token
    C->>API: Authorization: Bearer {token}
    API-->>C: Trả về dữ liệu (banks, webhooks,...)
```

---

## 🧾 Thông tin chi tiết

### **Endpoint**
`POST https://api-partner.pay2s.vn/v1/auth/authorize`

### **Headers**
| Tên header | Giá trị mẫu | Mô tả |
|-------------|-------------|-------|
| `Authorization` | `Basic base64(access_key:secret_key)` | Dạng xác thực cơ bản |
| `Content-Type` | `application/json` | Bắt buộc |

### **Ví dụ Base64**
Giả sử:
```
access_key = e222c2c10059cca0e27bf43d0438bba372
secret_key = 83f84c5a1d94ad4a1d3810292ad55a0d
```
→ Ghép chuỗi:  
`e222c2c10059cca0e27bf43d0438bba372:83f84c5a1d94ad4a1d3810292ad55a0d`  
→ Mã hoá Base64 thành:  
`ZT222c2c10059cca0e27bf43d0438bba372OjgzZjg0YzVhMWQ5NGFkNGExZDM4MTAyOTJhZDU1YTBk`

→ Header:
```
Authorization: Basic ZT222c2c10059cca0e27bf43d0438bba372OjgzZjg0YzVhMWQ5NGFkNGExZDM4MTAyOTJhZDU1YTBk
```

---

## 🧠 Phản hồi mẫu

### ✅ Thành công
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "expires_in": 3600
  }
}
```

### ❌ Lỗi xác thực
```json
{
  "success": false,
  "error": {
    "code": "BASIC_REQUIRED",
    "message": "Use Basic base64(access_key:secret_key)"
  }
}
```

---

## 🧩 Gọi API bằng Token

Sau khi nhận được **Bearer Token**, bạn có thể gọi các endpoint bảo mật khác như sau:

**Ví dụ:**
```
GET https://api-partner.pay2s.vn/v1/banks HTTP/1.1
Host: partner.pay2s.vn
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**Kết quả:**
```json
{
  "success": true,
  "data": [
    { "bank": "ACB", "accountNumber": "123456789", "status": "active" },
    { "bank": "VCB", "accountNumber": "987654321", "status": "inactive" }
  ]
}
```

---

::: tip 🔑 Gợi ý
- Token có hiệu lực **3600 giây (1 giờ)**. Sau khi hết hạn, cần gọi lại `/v1/auth/authorize` để lấy token mới.
- Hỗ trợ xác thực **Basic Auth → Bearer Token** (không cần tạo chữ ký HMAC thủ công).
:::


---

Nguồn trang: https://docs.pay2s.vn/partner/bank.html

# 🏦 Bank Subscription / Quản lý ngân hàng (theo Postman Collection)

Các API yêu cầu **Bearer Token** lấy từ `/v1/auth/authorize` (Basic → Bearer).

---

## 🔐 Header chung

```
Authorization: Bearer <token>
Content-Type: application/json
```

---

## 1) Thêm ngân hàng

**POST** `https://api-partner.pay2s.vn/v1/banks`

> Có nhiều biến thể theo từng ngân hàng / cơ chế: **OpenAPI (BIDV, ACB, …)** hoặc **Pay2S-api (personal/business)**.  
> Dưới đây là các **body mẫu đúng theo collection**.

### 1.1 OpenAPI – BIDV
```json
{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "cccd": "068095012120",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0708077478",
  "accEmail": "trongvy.nguyen@gmail.com"
}
```

- `merchantId`: yêu cầu với BIDV (được dùng khi sinh VA: tiền tố 963869 + mã).  
- Hệ thống sẽ **gửi OTP** → cần gọi bước *Xác nhận OTP* bên dưới.

### 1.2 OpenAPI – ACB
```json
{
  "type": "openapi",
  "bankShortName": "ACB",
  "accountNumber": "19354957",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0902506099"
}
```

> Với ACB, trường `bank_type` có thể mặc định **personal** (PERS) hoặc **business** (ORG) ở tầng core – collection mẫu để tối thiểu như trên.

### 1.3 Pay2S‑api – Personal (Internet Banking)
```json
{
  "type": "personal",
  "bankShortName": "VCB",
  "accountNumber": "0123456789",
  "username": "internet_banking_user",
  "password": "secret"
}
```

> Một số bank personal có thể trả về *OTP* hoặc *Hợp lệ* tùy quy trình xác minh.  
> Nếu trả về *OTP*, tiếp tục gọi `https://api-partner.pay2s.vn/v1/banks/confirm-otp`.

---

## 2) Xác nhận OTP (Confirm OTP)

**POST** `https://api-partner.pay2s.vn/v1/banks/confirm-otp`

### 2.1 BIDV (OpenAPI)
```json
{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "merchantId": "VYTEOO1", //Cần phải nhập hậu tố cho VA Number
  "otp": "016311"
}
```

### 2.2 ACB hoặc MBBank (OpenAPI)
```json
{
  "type": "openapi",
  "bankShortName": "ACB", //MBB
  "accountNumber": "19354957",
  "otp": "767523"
}
```

### 2.3 Pay2S‑api (Personal)
```json
{
  "type": "personal",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "username": "bidv_user",
  "password": "abc123",
  "otp": "767523"
}
```

> Trả về *Hợp lệ* → ngân hàng được kích hoạt. Nếu vẫn *OTP* → kiểm tra lại mã OTP hoặc thời hạn OTP.

---

## 3) Danh sách ngân hàng của user

**GET** `https://api-partner.pay2s.vn/v1/banks`

**Phản hồi mẫu:**
```json
{
  "status": true,
  "message": [
    {
      "id": 410,
      "username": "0123456789",
      "name": "NGUYEN VAN A",
      "accountNumber": "0123456789",
      "vaNumber": "963869789",
      "balance": 1000000,
      "created_at": "2025-10-14 10:42:11",
      "status": 1,
      "statusText": "Đang hoạt động",
      "bankName": "Asia Commercial Bank"
    }
  ]
}
```

> Lưu ý: với BIDV OpenAPI, `vaNumber` có thể hiển thị dạng **963869 + &lt;shortCode&gt;**.

---

## 4) Bật / Tắt trạng thái ngân hàng

**PATCH** `https://api-partner.pay2s.vn/v1/banks/{id}/status`

**Phản hồi mẫu:**
```json
{
  "status": true,
  "message": "Cập nhật trạng thái ngân hàng thành công.",
  "newStatus": 1
}
```

> Chỉ bật được khi liên kết đã **thành công** (không còn trạng thái `hide` treo OTP).

---

## 5) Xoá ngân hàng

**DELETE** `https://api-partner.pay2s.vn/v1/banks/{id}`

- Một số ngân hàng OpenAPI (ví dụ MBB/ACB khi chưa active) sẽ trả về yêu cầu **OTP xoá**.

**Phản hồi mẫu:**
```json
{
  "status": true,
  "message": "Xóa ngân hàng.",
  "OTP": 1,
  "type": "SMS"
}
```

### 5.1 Xác nhận xoá (OTP)

**POST** `https://api-partner.pay2s.vn/v1/banks/{id}/delete-confirm`

```json
{ "otp": "160241" }
```

**Phản hồi mẫu:**
```json
{ "status": true, "message": "Xóa ngân hàng thành công" }
```

---

## 6) Thống kê tóm tắt (Summary)

**GET** `https://api-partner.pay2s.vn/v1/banks/summary`

> Trả về tổng quan số lượng ngân hàng đã liên kết theo từng `bankName/shortBankName`, kèm tổng số.

**Ví dụ phản hồi rút gọn:**
```json
{
  "status": true,
  "bankCounts": [
    { "bankName": "Vietcombank", "shortBankName": "VCB", "count": 2 },
    { "bankName": "BIDV", "shortBankName": "BIDV", "count": 1 }
  ],
  "total": 3
}
```

---

## 🧪 cURL mẫu

### Thêm BIDV (OpenAPI)
```bash
curl -X POST https://api-partner.pay2s.vn/v1/banks  -H "Authorization: Bearer <token>"  -H "Content-Type: application/json"  -d '{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "cccd": "068095012120",
  "merchantId": "VYTEOO1",
  "accName": "NGUYEN TRONG VY",
  "accMobile": "0708077478",
  "accEmail": "trongvy.nguyen@gmail.com"
 }'
```

### Xác nhận OTP BIDV
```bash
curl -X POST https://api-partner.pay2s.vn/v1/banks/confirm-otp  -H "Authorization: Bearer <token>"  -H "Content-Type: application/json"  -d '{
  "type": "openapi",
  "bankShortName": "BIDV",
  "accountNumber": "8810281999",
  "merchantId": "VYTEOO1",
  "otp": "016311"
 }'
```

### Danh sách ngân hàng
```bash
curl -X GET "https://api-partner.pay2s.vn/v1/banks"  -H "Authorization: Bearer <token>"
```

### Bật/Tắt trạng thái
```bash
curl -X PATCH "https://api-partner.pay2s.vn/v1/banks/410/status"  -H "Authorization: Bearer <token>"
```

### Xoá ngân hàng
```bash
curl -X DELETE "https://api-partner.pay2s.vn/v1/banks/410"  -H "Authorization: Bearer <token>"
```

### Xác nhận xoá (OTP)
```bash
curl -X POST "https://api-partner.pay2s.vn/v1/banks/410/delete-confirm"  -H "Authorization: Bearer <token>"  -H "Content-Type: application/json"  -d '{ "otp": "160241" }'
```

---

::: tip Lưu ý
- Body mẫu ở trên **được lấy đúng** từ Postman collection (BIDV, ACB, personal).  
- Với BIDV OpenAPI, `merchantId` là bắt buộc và VA hiển thị dạng `963869<code>`.  
- Nếu API trả về `OTP = 1`, bạn phải thực hiện bước *Confirm OTP* tương ứng.
:::


---

Nguồn trang: https://docs.pay2s.vn/partner/khai-niem.html

---
title: Khái niệm Partner API
---

# 🔗 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:**

1. Đối tác đăng nhập Pay2S.vn → vào mục **Partner API** để lấy **Access Key** và **Secret Key**  
2. Dùng Basic Auth (`Authorization: Basic base64(access:secret)`) để cấp **Bearer Token** tạm thời  
3. 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) |

::: tip 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 |


---

Nguồn trang: https://docs.pay2s.vn/partner/postman.html

# 📦 Postman Collection – Pay2S Partner API

Tải về và import **Postman Collection** để thử nhanh các API của **Pay2S Partner** (Authentication, Banks, Webhook, Analytics).  
Bộ sưu tập này khớp với tài liệu và các route hiện hành.

---

## ⬇️ Tải xuống

- **Collection (.json):** [pay2s-partner.postman_collection.json](https://docs.pay2s.vn/downloads/pay2s-partner.postman_collection.json)

> Sau khi tải về, mở Postman → `Import` → chọn file `.json` này.

---

## 🔧 Biến môi trường gợi ý (Environment)

Bạn có thể tạo **Environment** trong Postman với các biến sau để tiện sử dụng:

| Biến | Ví dụ | Mô tả |
|---|---|---|
| `base_url` | `https://api-partner.pay2s.vn` | Base URL Partner API |
| `access_key` | `PAY2SXXXXXXXX...` | Lấy từ my.pay2s.vn (Partner) |
| `secret_key` | `SECRETXXXXXXXX...` | Lấy từ my.pay2s.vn (Partner) |
| `bearer_token` | *(để trống, sẽ set sau)* | Token trả về từ `/v1/auth/authorize` |

---

## 🚀 Quy trình dùng nhanh

1. Mở request **Authorize** trong folder **Authentication**.
2. Đặt header `Authorization: Basic base64(access_key:secret_key)`.
3. Send để nhận `token` → copy vào **Environment**: `bearer_token`.
4. Dùng các request còn lại (Banks, Webhooks, Metrics) với header:
   ```
   Authorization: Bearer {{bearer_token}}
   ```

---

## 🧪 Mẹo test nhanh

- Có sẵn các request:
  - `POST https://api-partner.pay2s.vn/v1/auth/authorize` – Lấy token
  - `POST https://api-partner.pay2s.vn/v1/banks` – Thêm ngân hàng (OpenAPI ACB/BIDV, personal, business)
  - `POST https://api-partner.pay2s.vn/v1/banks/confirm-otp` – Xác nhận OTP
  - `GET https://api-partner.pay2s.vn/v1/banks` – Danh sách
  - `DELETE https://api-partner.pay2s.vn/v1/banks/:id` & `POST /v1/banks/:id/delete-confirm` – Xoá & xác nhận
  - `GET https://api-partner.pay2s.vn/v1/webhooks` / `POST /v1/webhooks` – Quản lý webhook
  - `GET https://api-partner.pay2s.vn/v1/webhooks/history` – Lịch sử gọi webhook
  - `POST https://api-partner.pay2s.vn/v1/webhooks/:history_id/resend` – Gửi lại payload
  - `GET https://api-partner.pay2s.vn/v1/metrics/*` – Thống kê

- Nếu bị **401 Unauthorized**, hãy kiểm tra lại token hết hạn (mặc định 3600s).

---

## 🧯 Lỗi hay gặp

- **OTP không hợp lệ**: OTP có thời hạn, thử gửi lại OTP và xác nhận ngay.

---

Chúc bạn tích hợp thành công! Nếu cần hỗ trợ, truy cập **Trung tâm khách hàng** hoặc mục **Hỗ trợ & Báo lỗi** trong thanh điều hướng.


---

Nguồn trang: https://docs.pay2s.vn/partner/webhook.html

# 🔔 Webhook / Thông báo giao dịch tự động

## 🧭 Giới thiệu

**Webhook Partner API** cho phép đối tác nhận thông báo **tự động (IN/OUT)** mỗi khi có giao dịch mới phát sinh từ các tài khoản ngân hàng đã liên kết.  
Đây là cơ chế **push notification** theo thời gian thực — giúp hệ thống đối tác xử lý thanh toán, đối soát, hoặc cập nhật hóa đơn tức thì.

---

## 🔐 Header chung

```
Authorization: Bearer <token>
Content-Type: application/json
```

---

## 1️⃣ Tạo webhook mới

**POST** `https://api-partner.pay2s.vn/v1/webhooks`

### **Body mẫu**
```json
{
  "user_bank_id": 25,
  "webhook_url": "https://merchant-domain.com/pay2s/handler",
  "type": "IN"
}
```

### **Giải thích**
| Trường | Mô tả |
|--------|-------|
| `user_bank_id` | ID của tài khoản ngân hàng cần gắn webhook (lấy từ `/v1/banks`) |
| `webhook_url` | URL nhận dữ liệu giao dịch |
| `type` | Loại giao dịch cần nhận (`IN`, `OUT`, `ALL`) |

### **Phản hồi mẫu**
```json
{
  "status": true,
  "message": "Webhook đã được thêm thành công.",
  "token": "e3a19a5a65a48ff3b3ef198fcb2a5a6c"
}
```

---

## 2️⃣ Danh sách webhook

**GET** `https://api-partner.pay2s.vn/v1/webhooks`

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": [
           {
            "id": 1306,
            "user_bank_id": 410,
            "type": "ALL",
            "created_at": "2026-03-24 16:52:27",
            "updated_at": "2026-03-24 17:42:38",
            "status": "1",
            "username": "",
            "accountNumber": "8810281999",
            "vaNumber": "9638698888",
            "bankName": "Ngân hàng Đầu Tư và Phát Triển VN (BIDV)",
            "shortBankName": "BIDV",
            "vaNumberFull": "9638698888",
            "webhook_url": "https://example4.com/webhook",
            "token": "6df7dde305d4353ebdc00d6f0e260e1e72cb4c1c6779f1bdcd",
            "uses_custom_config": true,
            "has_own_token": true
        }
  ]
}
```

---

## 3️⃣ Cập nhật webhook

**PATCH** `https://api-partner.pay2s.vn/v1/webhooks/{id}`

### **Body mẫu**
```json
{
  "webhook_url": "https://merchant-domain.com/pay2s/new-handler",
  "type": "ALL"
}
```

**Phản hồi:**
```json
{
  "status": true,
  "message": "Webhook đã được cập nhật thành công."
}
```

---

## 4️⃣ Bật / Tắt trạng thái webhook

**PATCH** `https://api-partner.pay2s.vn/v1/webhooks/{id}/toggle`

> Cho phép nhanh chóng **vô hiệu hóa / kích hoạt** webhook mà không cần xóa.

### **Phản hồi mẫu**
```json
{
  "status": true,
  "message": "Trạng thái webhook đã được cập nhật thành công."
}
```

---

## 5️⃣ Xoá webhook

**DELETE** `https://api-partner.pay2s.vn/v1/webhooks/{id}`

### **Phản hồi mẫu**
```json
{
  "status": true,
  "message": "Webhook đã được xóa thành công."
}
```

> Khi xoá, hệ thống cũng sẽ xoá các bản ghi liên quan trong `transaction_webhook_history` để tránh trùng lặp.

---

## 6️⃣ Lịch sử gọi webhook

**GET** `https://api-partner.pay2s.vn/v1/webhooks/history`

Hiển thị toàn bộ các lần hệ thống Pay2S đã **gửi thông báo giao dịch** đến endpoint webhook của bạn.

### **Phản hồi mẫu**
```json
{
  "status": true,
  "data": [
    {
      "id": 991,
      "webhook_id": 101,
      "endpoint": "https://merchant-domain.com/pay2s/handler",
      "status_code": 200,
      "status": 1,
      "call_time": "2025-10-14 11:00:00",
      "response": "Transactions sent successfully",
      "payload": {
        "transactions": [
          {
            "id": 3521,
            "gateway": "ACB",
            "transactionDate": "2025-10-14 10:59:30",
            "transactionNumber": "FT253146879VN",
            "vaNumber": "963869789",
            "accountNumber": "19354957",
            "content": "NAPTIEN MOMO 963869789",
            "transferType": "IN",
            "transferAmount": 200000,
            "checksum": "a8e97b098f45f6e2dfdbf33d10d1dc4b"
          }
        ]
      }
    }
  ]
}
```

---

## 7️⃣ Gửi lại webhook (Resend)

**POST** `https://api-partner.pay2s.vn/v1/webhooks/{history_id}/resend`

> Cho phép đối tác yêu cầu **Pay2S gửi lại payload** của giao dịch bị lỗi (ví dụ status_code ≠ 200).

### **Phản hồi mẫu**
```json
{
  "status": true,
  "message": "Gửi lại giao dịch thành công và cập nhật trạng thái webhook."
}
```

---

## 🔁 Cấu trúc Payload gửi đến Webhook của bạn

Khi có giao dịch mới, Pay2S sẽ gửi **POST** tới `webhook_url` mà bạn đã đăng ký.

### **Payload mẫu**
```json
{
  "transactions": [
    {
      "id": 3521,
      "gateway": "ACB",
      "transactionDate": "2025-10-14 10:59:30",
      "transactionNumber": "FT253146879VN",
      "vaNumber": "963869789",
      "accountNumber": "19354957",
      "content": "NAPTIEN MOMO 963869789",
      "transferType": "IN",
      "transferAmount": 200000,
      "checksum": "a8e97b098f45f6e2dfdbf33d10d1dc4b"
    }
  ]
}
```

### **Header gửi đi**
```
Content-Type: application/json
Authorization: Bearer <webhook_token>
```

### **Phản hồi yêu cầu**
Để đánh dấu nhận thành công, endpoint webhook của bạn cần trả về:
```json
{ "success": true }
```

Nếu trả về khác (`success=false`, hoặc HTTP 4xx/5xx), hệ thống sẽ ghi log lỗi và có thể cho phép **gửi lại thủ công** qua API `resend`.

---

## 🧪 cURL mẫu

### Tạo Webhook
```bash
curl -X POST https://api-partner.pay2s.vn/v1/webhooks \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
  "user_bank_id": 25,
  "webhook_url": "https://merchant-domain.com/pay2s/handler",
  "type": "IN"
 }'
```

### Danh sách Webhook
```bash
curl -X GET https://api-partner.pay2s.vn/v1/webhooks \
 -H "Authorization: Bearer <token>"
```

### Gửi lại giao dịch
```bash
curl -X POST https://api-partner.pay2s.vn/v1/webhooks/991/resend \
 -H "Authorization: Bearer <token>"
```

---

::: tip Ghi chú
- Mỗi webhook được cấp **token riêng** (trường `token` trong dữ liệu webhook). Khi Pay2S gọi webhook của bạn, token này nằm trong header Authorization.
- Hệ thống ghi log mọi lần gửi — có thể truy xuất qua `/v1/webhooks/history`.
:::