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 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:** Đăng nhập [merchant.pay2s.vn](https://merchant.pay2s.vn) → **Bankhub → thiết lập** để 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**

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",
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 3600
  }
}
```

### ❌ Lỗi xác thực
```json
{
    "success": false,
    "error": {
        "code": "CREDENTIALS_INVALID",
        "message": "Thông tin xác thực không hợp lệ."
    }
}
```

---

## 🧩 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: api-partner.pay2s.vn
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Xem cấu trúc phản hồi và cách sử dụng `id` trong [Danh sách tài khoản ngân hàng](./bank.md#bank-list).

---

::: 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).
:::


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

### Xác thực Partner

<div class="doc-api-actions" data-doc-api-actions><a class="try-button" data-doc-playground href="/playground/?api=authorize">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 /v1/auth/authorize`

Body:

```json
{}
```

HTTP 200. Response:

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