API Giao Dịch
Nội dung Markdown đầy đủ của trang tài liệu.
# 💳 API Giao Dịch
API giao dịch là các giao dịch ngân hàng đã phát sinh. Bạn có thể truy vấn thông tin chi tiết một giao dịch, danh sách giao dịch, đếm số lượng giao dịch.
## 🚦 Giới hạn truy cập
:::: warning API Rate Limits
Hệ thống Pay2S giới hạn **tối đa 60 request/phút**.
Nếu vượt quá giới hạn này, sẽ trả về lỗi:
``429 Too Many Requests``
::::
## 📌 API: Lấy danh sách giao dịch
### Method
<div class="code-block">Method: <span class="http-method">POST</span></div>
### 🔗 Endpoint
<div class="code-block">https://api.pay2s.vn/userapi/transactions</div>
### 🔐 Header
```json
{
"Content-Type": "application/json",
"pay2s-token": "DAN_TOKEN_BASE64_CUA_BAN_VAO_DAY"
}
```
### Lấy Secret Key ở đâu?
1. Đăng nhập tài khoản Pay2S tại [trang Tích hợp Website/Application](https://pay2s.vn/client/integration/webapp).
2. Nếu đi từ menu, chọn **Tích hợp → Website/Application**.
3. Tìm dòng **Secret key**, bấm nút **sao chép** ở dòng đó. Không lấy Partner code hoặc Access key.
4. Dán Secret Key vào công cụ bên dưới, bấm **Tạo pay2s-token**, rồi **Sao chép token**.
Nếu thấy thông báo **“Khóa tích hợp đang được bảo vệ”**, hãy dùng tài khoản chính hoặc nhờ chủ tài khoản cấp quyền xem và sao chép khóa tích hợp.
### Chuyển Secret Key thành pay2s-token
`pay2s-token` được tạo bằng **Base64 của nguyên chuỗi Secret Key, đúng một lần**. Không cần đăng ký hoặc xin thêm token riêng.
Ví dụ minh họa (không dùng để gọi API thật):
```text
Secret Key: example-secret
pay2s-token: ZXhhbXBsZS1zZWNyZXQ=
```
<div data-token-helper></div>
Công cụ trên trang tài liệu chuyển đổi ngay trong trình duyệt, không gửi khóa lên máy chủ và không lưu khóa vào bộ nhớ trình duyệt. Base64 có thể giải mã ngược: giữ kín cả Secret Key và token, không gửi cho AI hoặc đặt trong mã frontend công khai.
### Dán token vào đâu?
Trong **Postman → Headers**, thêm dòng:
| Key | Value |
| --- | --- |
| `pay2s-token` | Dán token vừa sao chép |
| `Content-Type` | `application/json` nếu API gửi JSON body |
Ở tab **Authorization**, chọn **No Auth**. Giá trị header chỉ là token: **không thêm `Bearer`, `Basic` hoặc dấu ngoặc kép**.
Nếu tự viết backend, có thể tạo token trực tiếp:
```js
// Node.js — Secret Key lấy từ biến môi trường của backend
const token = Buffer.from(process.env.PAY2S_SECRET_KEY, 'utf8').toString('base64');
// Gửi header: { 'pay2s-token': token }
```
```php
// PHP — Secret Key lấy từ biến môi trường của backend
$token = base64_encode(getenv('PAY2S_SECRET_KEY'));
// Gửi header: 'pay2s-token: ' . $token
```
**Lỗi thường gặp:** sao chép nhầm Access key; dùng nguyên Secret Key chưa chuyển đổi; chuyển Base64 hai lần; dính khoảng trắng hoặc xuống dòng; dùng token cũ sau khi đã đổi Secret Key. Đây không phải JWT hoặc token đăng nhập Dashboard.
### 📥 Request Parameters
| Key | Type | Required | Description |
| ------------ | ---------- | -------- | -------------------------------------------------------------------------------------------------- |
| `bankAccounts` | String | Không | Số tài khoản muốn lọc giao dịch. Bỏ qua để lấy tất cả. |
| `begin ` | String | ✓ | Ngày bắt đầu (định dạng: dd/mm/yyyy) |
| `end` | String | ✓ | Ngày kết thúc (định dạng: dd/mm/yyyy) |
### 🧪 Sample Request
```json
{
"bankAccounts": "P2S99999999",
"begin": "01/10/2026",
"end": "31/10/2026"
}
```
### 📤 Sample Response
```json
{
"status": true,
"messages": "Thành công",
"transactions": [
{
"id": 33069896,
"transaction_date": "2026-10-11 02:19:33",
"transaction_id": "DEMO-20261011021933-1720299E09",
"account_number": "P2S99999999",
"vaNumber": null,
"bank": "ACB",
"amount": 250000,
"description": "TT817916599723201625c7",
"type": "IN",
"checksum": "5ef40ca4c071340042e2db7c2e9a44cf",
"detail": {
"remitterName": "KHÁCH HÀNG DEMO",
"remitterAccountNumber": "P2SDEMO",
"issuerBankName": "ACB DEMO",
"reciprocalBankCode": null
}
},
{
"id": 33069175,
"transaction_date": "2026-10-11 01:29:56",
"transaction_id": "DEMO-20261011012956-909ED7DF11",
"account_number": "P2S99999999",
"vaNumber": null,
"bank": "ACB",
"amount": 250000,
"description": "TT01791656993596ca2535",
"type": "IN",
"checksum": "9d25c53367294bb8267c3862f3539114",
"detail": {
"remitterName": "KHÁCH HÀNG DEMO",
"remitterAccountNumber": "P2SDEMO",
"issuerBankName": "ACB DEMO",
"reciprocalBankCode": null
}
}
]
}
```
| Key | Description |
| ------------ | ---------- |
| id | ID giao dịch duy nhất trên hệ thống Pay2S |
| transaction_date | Thời gian giao dịch (YYYY-MM-DD HH:mm:ss) |
| transaction_id | Mã giao dịch gốc từ phía ngân hàng |
| account_number | Số tài khoản ngân hàng nhận/gửi tiền|
| vaNumber | Số tài khoản ảo; có thể là null |
| bank | BankCode (ví dụ: ACB, VCB...) |
| amount | Số tiền giao dịch (đơn vị: VNĐ) |
| description | Nội dung chuyển khoản |
| type | Loại giao dịch: `IN` (nhận tiền), `OUT` (chuyển tiền)|
| checksum | Mã duy nhất của giao dịch được sinh ra từ Pay2S|
## Request và response đối chiếu ngày 11/10/2026
Các mẫu dưới đây giữ cấu trúc trường và kiểu dữ liệu. Khóa, chữ ký, URL phiên đã được thay bằng placeholder; danh sách chỉ giữ tối đa hai phần tử và dữ liệu ảnh/PDF/XML dài được rút gọn. Không sao chép placeholder để gọi API thật.
### Danh sách giao dịch
<div class="doc-api-actions" data-doc-api-actions><a class="try-button" data-doc-playground href="/playground/?api=transactions">Thử API trong Playground ↗</a><a class="try-button experience-button" data-doc-experience hidden>Trải nghiệm ↗</a></div>
**Đã gọi API demo/UAT.**
`POST /userapi/transactions`
Body:
```json
{
"bankAccounts": "P2S99999999",
"begin": "01/10/2026",
"end": "31/10/2026"
}
```
HTTP 200. Response:
```json
{
"status": true,
"messages": "Thành công",
"transactions": [
{
"id": 33069896,
"transaction_date": "2026-10-11 02:19:33",
"transaction_id": "DEMO-20261011021933-1720299E09",
"account_number": "P2S99999999",
"vaNumber": null,
"bank": "ACB",
"amount": 250000,
"description": "TT817916599723201625c7",
"type": "IN",
"checksum": "5ef40ca4c071340042e2db7c2e9a44cf",
"detail": {
"remitterName": "KHÁCH HÀNG DEMO",
"remitterAccountNumber": "P2SDEMO",
"issuerBankName": "ACB DEMO",
"reciprocalBankCode": null
}
},
{
"id": 33069175,
"transaction_date": "2026-10-11 01:29:56",
"transaction_id": "DEMO-20261011012956-909ED7DF11",
"account_number": "P2S99999999",
"vaNumber": null,
"bank": "ACB",
"amount": 250000,
"description": "TT01791656993596ca2535",
"type": "IN",
"checksum": "9d25c53367294bb8267c3862f3539114",
"detail": {
"remitterName": "KHÁCH HÀNG DEMO",
"remitterAccountNumber": "P2SDEMO",
"issuerBankName": "ACB DEMO",
"reciprocalBankCode": null
}
}
]
}
```