PayFS Documentation

API Token là thông tin xác thực để hệ thống của bạn gọi API PayFS. Mỗi token thuộc về một User Account và được cấp quyền trên từng Workspace cụ thể.

Đừng nhầm API Token với Webhook API Key. API Token dùng khi bạn gọi PayFS. Webhook API Key dùng khi PayFS gọi bạn, gửi qua header X-Client-API-Key. Hai khóa hoàn toàn độc lập.

Tạo API Token

Đăng nhập Client Portal
Mở mục API Token
Chọn Tạo API Token
Đặt tên, chọn thời điểm hết hạn
Chọn những Workspace mà token được phép truy cập
Chọn quyền cho từng Workspace
Sao chép token và lưu vào nơi an toàn

Phân quyền

Quyền được cấp theo từng cặp tài nguyên và hành động, trên từng Workspace.

Tài nguyên	Quyền
Workspace	Xem, Thay đổi, Xóa, Quản lý thành viên
Tài khoản ngân hàng	Xem, Thay đổi, Xóa
Webhook	Xem, Thay đổi, Xóa
Liên kết thanh toán	Xem (`payment_links:read`), Thay đổi (`payment_links:write`)

Quyền thực tế của token không bao giờ vượt quá quyền hiện tại của User Account đã tạo token. Nếu quyền của User Account trên một Workspace bị thu hẹp, quyền của token cũng bị thu hẹp theo.

Gọi API

Gửi token trong header Authorization theo lược đồ Bearer.

curl https://api.payfs.vn/v1.1/transactions \
  -H "Authorization: Bearer $PAYFS_API_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.payfs.vn/v1.1/transactions', {
  headers: {
    'Authorization': `Bearer ${process.env.PAYFS_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

Phiên bản API

Dùng /v1.1. Mọi ví dụ trong tài liệu này đều theo phiên bản đó.

https://api.payfs.vn/v1.1/...

Luôn ghi rõ phiên bản trong đường dẫn. Đừng dựa vào một phiên bản mặc định.

Xoay vòng và thu hồi

Xoay vòng: sinh giá trị mới cho token. Giá trị cũ ngừng hoạt động ngay lập tức.
Thu hồi: vô hiệu hóa token. Mọi yêu cầu dùng token này sẽ bị từ chối ngay.

Nên xoay vòng định kỳ, và thu hồi ngay khi nghi ngờ token bị lộ.

Nguyên tắc nên theo

Mỗi hệ thống dùng một token riêng, để thu hồi được từng cái mà không ảnh hưởng cái khác
Chỉ cấp quyền tối thiểu mà hệ thống đó thực sự cần
Lưu token trong biến môi trường, không commit vào Git
Không ghi token vào log
Đặt thời điểm hết hạn ngay khi tạo

Lỗi thường gặp

Mọi lỗi đều trả về cùng cấu trúc. error.code cho biết loại lỗi, error.traceId giúp bộ phận hỗ trợ tra đúng request của bạn.

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "errorCode": 20001,
    "message": "Authentication failed",
    "traceId": "trace_01HK...",
    "messageKey": "auth/authentication-error"
  },
  "meta": { "timestamp": "2026-08-23T02:02:55.371Z" }
}

Mã	`error.code`	Cách xử lý
401	`AUTHENTICATION_ERROR`	Token sai, hết hạn, hoặc đã bị thu hồi. Kiểm tra header đúng dạng `Authorization: Bearer <token>`.
403	`INSUFFICIENT_PERMISSIONS`	Token không có quyền trên Workspace bạn đang gọi. Sửa phạm vi quyền trong Client Portal.
429	`RATE_LIMIT_ERROR`	Gọi quá nhiều. Thử lại với khoảng chờ tăng dần, hoặc nâng gói dịch vụ.

API Token