🔐 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 để 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

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

Ví dụ Base64

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

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

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

❌ Lỗi xác thực

{
    "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

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:

{}

HTTP 200. Response:

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