# YU Bank API v3

> Tài liệu tích hợp giao dịch ngân hàng và webhook dành cho lập trình viên và AI coding agents.

## Nguồn chuẩn
- Tài liệu cho người dùng: https://bank.yu.com.vn/docs-v3
- OpenAPI 3.1: https://bank.yu.com.vn/openapi.json
- Đăng ký tài khoản: https://bank.yu.com.vn/auth/register-basic
- Quản lý kết nối ngân hàng: https://bank.yu.com.vn/bank-accounts-v3
- Quản lý webhook: https://bank.yu.com.vn/client/webhooks-v3

## API lịch sử giao dịch
`GET https://bank.yu.com.vn/v3/{bank}/transhistory/{token}?limit=20`

- `bank`: mã ngân hàng, ví dụ `acb`, `vietcombank`, `vpbank`.
- `token`: token riêng của tài khoản ngân hàng. Chỉ lưu ở backend/secret manager.
- `limit`: 1..500, mặc định 20.
- Không gọi endpoint có token từ browser hoặc mobile app không tin cậy.

## Webhook
- Nhận `POST application/json` qua HTTPS.
- Xác minh `X-APIBank-Timestamp` và từ chối nếu lệch quá 300 giây.
- Chữ ký là hex HMAC-SHA256 của `timestamp + "." + raw_body` với webhook secret.
- Chống trùng bằng unique index trên `X-APIBank-Event-Id`/`event_id`.
- Lưu event bền vững, đưa xử lý nặng vào queue rồi trả HTTP 2xx trong dưới 12 giây.
- Retry giữ nguyên `event_id`; không cộng tiền lần thứ hai.

## Quy tắc sinh mã
1. Đọc OpenAPI trước khi viết client.
2. Dùng biến môi trường cho token và secret; không log hai giá trị này.
3. Có timeout, retry có giới hạn và xử lý idempotent.
4. Không tự tạo endpoint, không suy diễn trường dữ liệu ngoài tài liệu.
5. Khi cần webhook payload và mã xác minh PHP/Node, đọc mục Webhook tại `/docs-v3#webhook`.