🔐 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 → 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

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

Giả sử:

access_key = e222c2c10059cca0e27bf43d0438bba372
secret_key = 83f84c5a1d94ad4a1d3810292ad55a0d

→ Ghép chuỗi:
e222c2c10059cca0e27bf43d0438bba372:83f84c5a1d94ad4a1d3810292ad55a0d
→ Mã hoá Base64 thành:
ZT222c2c10059cca0e27bf43d0438bba372OjgzZjg0YzVhMWQ5NGFkNGExZDM4MTAyOTJhZDU1YTBk

→ Header:

Authorization: Basic ZT222c2c10059cca0e27bf43d0438bba372OjgzZjg0YzVhMWQ5NGFkNGExZDM4MTAyOTJhZDU1YTBk

---

🧠 Phản hồi mẫu

✅ Thành công

{
  "success": true,
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
    "expires_in": 3600
  }
}

❌ Lỗi xác thực

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

---

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