Authentication / Xác thực đối tác

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

# 🔐 Authentication / Xác thực đối tác

## 🧭 Giới thiệu

Hệ thống **Pay2S OneQR** 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 người dùng.

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ư `/api/vcb/v1/qr/create`, `api/vcb/v1/qr/cancel`, 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 /api/auth/token (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 http://api.pay2s.vn/api/auth/token`

### **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**

Ví dụ với khóa minh họa `example-access` và `example-secret`:

```text
Chuỗi trước khi chuyển: example-access:example-secret
Authorization: Basic ZXhhbXBsZS1hY2Nlc3M6ZXhhbXBsZS1zZWNyZXQ=
```

Thay bằng khóa của đúng hệ thống đang tích hợp; mã hóa nguyên chuỗi `access_key:secret_key` một lần. Không dùng `pay2s-token` của API giao dịch ở đây.

---

## 🧠 Phản hồi mẫu

### ✅ Thành công
```json
{
  "success": true,
  "data": {
    "token_type": "Bearer",
    "token": "<TOKEN>",
    "expires_in": 3600
  }
}
```

### ❌ Lỗi xác thực
```json
{
    "success": false,
    "message": "Authentication failed",
    "data": null,
    "error": "Request failed with status code 401"
}
```

---

## Gọi API bằng Token

Lấy `data.token` từ response xác thực, gửi header `Authorization: Bearer <TOKEN>` khi gọi OneQR. Không nhầm với `data.access_token` của Partner API.

Playground OneQR hiện mô phỏng; chưa kiểm chứng response với nhà cung cấp thật trong đợt rà soát này.


## 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.

### OneQR · Xác thực

<div class="doc-api-actions" data-doc-api-actions><a class="try-button" data-doc-playground href="/playground/?api=oneqr-authorize">Thử API trong Playground ↗</a><a class="try-button experience-button" data-doc-experience hidden>Trải nghiệm ↗</a></div>

**Mô phỏng; chưa xác minh với API nhà cung cấp.** Giữ mô phỏng theo cấu hình demo. Chưa có API OneQR thật để xác minh lại hợp đồng nhà cung cấp.

`POST /api/auth/token`

Body:

```json
{}
```

HTTP 200. Response:

```json
{
  "success": true,
  "data": {
    "token_type": "Bearer",
    "token": "<TOKEN>",
    "expires_in": 3600
  }
}
```