🔐 Authentication / Xác thực đối tác

✧ Mở bằng AI

Sao chép tài liệu, mở AI rồi dán vào cuộc trò chuyện.

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

Bước 1: Đăng nhập merchant.pay2s.vn → Bankhub → thiết lập để lấy Access Key và Secret Key.
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.
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

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",
    "access_token": "<ACCESS_TOKEN>",
    "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.

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

Thử API trong Playground ↗

Đã gọi API demo/UAT.

POST /v1/auth/authorize

Body:

{}

HTTP 200. Response:

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