Xác thực API ngân hàng MONA Pay: Bearer token và X-Client-Secret

Video hướng dẫn

Mọi lệnh gọi API MONA Pay cần header Authorization: Bearer <access_token>. Máy chủ và AI agent lấy token từ POST /api/v1/oauth/token; phiên dashboard lấy token từ POST /api/v1/client/login. Với token đăng nhập bằng mật khẩu, mọi lệnh ghi POST, PUT, PATCH và DELETE bắt buộc gửi thêm X-Client-Secret. Token client credentials không bắt buộc gửi lại header này, nhưng MONA Pay vẫn khuyến nghị luôn gửi. Mọi response đều bọc trong một khung chung {"success": true, "message": "...", "data": ...}.

Base URL

Tài khoản đăng ký xong dùng được ngay: đăng nhập, tạo API key, không cần ai duyệt. Muốn thử không tốn tiền: POST /api/v1/sandbox/transactions (Bearer + X-Client-Secret) với amount, description và tuỳ chọn số tài khoản, transaction_code → hệ tạo một giao dịch giả, bắn các kênh thông báo như tiền thật, không tính hạn mức. Chưa nối ngân hàng vẫn chạy được vì MONA Pay tự cấp VA SBX…; xem Sandbox.

Cách dành cho máy chủ và AI agent: client credentials

Không đưa username hay mật khẩu cho máy. Tạo API key ở dashboard (API Keys → Tạo key) để có client_id và client_secret, rồi đổi ra Bearer token:

curl -X POST https://api.monapay.vn/api/v1/oauth/token \
  -d "grant_type=client_credentials&client_id=client_xxx&client_secret=xxx"

{ "success": true, "message": "Cấp access token thành công", "data": { "access_token": "…", "token_type": "Bearer", "expires_in": 3600, "scope": "*" } }

Token hạn 3.600 giây; hết hạn thì gọi lại, không cần refresh token. Máy chủ đã kiểm client_secret khi cấp token nên không bắt buộc gửi lại X-Client-Secret ở từng lệnh ghi. SDK và MCP chính thức vẫn gửi kèm, và MONA Pay khuyến nghị làm vậy để một token lộ qua log hoặc proxy cũng không thể tự ý đổi cấu hình. Tài khoản bật xác thực 2 lớp vẫn dùng cách này bình thường, vì OTP chỉ áp cho đăng nhập bằng mật khẩu. SDK và MCP của MONA Pay đọc MONAPAY_CLIENT_ID và MONAPAY_CLIENT_SECRET từ biến môi trường và tự làm bước cấp token.

Khung response chung

Mọi endpoint trả về cùng một khung, kể cả khi lỗi:

{
  "success": true,
  "message": "Success",
  "data": { }
}

Lỗi validate (thiếu trường, sai kiểu) trả HTTP 422 theo chuẩn FastAPI với detail[] liệt kê từng trường sai.

Hai lớp xác thực

Giữ token và secret ở biến môi trường, không ghi cứng trong code, không commit lên git.

• Token từ POST /api/v1/client/login: mọi lệnh ghi POST, PUT, PATCH và DELETE bắt buộc kèm X-Client-Secret; thiếu header này, MONA Pay trả 401 Thiếu X-Client-Secret.
• Token từ POST /api/v1/oauth/token: MONA Pay đã kiểm client_secret khi cấp token nên không đòi lại header ở từng lệnh ghi. SDK và MCP chính thức vẫn gửi kèm.

MONA Pay khuyến nghị luôn gửi X-Client-Secret để token lộ qua log hoặc proxy cũng không thể tự ý đổi cấu hình.

POST /api/v1/client/register-client

Tạo tài khoản mới. Không cần xác thực. Tài khoản tạo xong dùng được ngay, đăng nhập liền không cần duyệt. Đăng ký qua form tại my.monapay.vn/auth (tab Đăng ký) cũng đi qua đúng endpoint này.

curl -X POST https://api.monapay.vn/api/v1/client/register-client \
  -H 'Content-Type: application/json' \
  -d '{"username":"shopabc","password":"MatKhauManh#2026","name":"Shop ABC"}'

Response 200/201:

{ "success": true, "message": "Client registered successfully", "data": {} }

POST /api/v1/client/login

Đổi username + mật khẩu lấy access_token. Không cần xác thực.

Response 200:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "access_token": "Zx9...64-ky-tu-url-safe",
    "expires_in": 86400,
    "token_type": "Bearer"
  }
}

expires_in tính bằng giây. Hết hạn thì gọi login lại, không có refresh token. Nếu tài khoản bật 2FA trong dashboard, bước đăng nhập trên web sẽ hỏi thêm mã OTP; gọi API trực tiếp thì dùng tài khoản chưa bật 2FA hoặc liên hệ đội MONA.

cURL

curl -X POST https://api.monapay.vn/api/v1/client/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"shopabc","password":"MatKhauManh#2026"}'

PHP

<?php
$res = json_decode(file_get_contents('https://api.monapay.vn/api/v1/client/login', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['username' => getenv('MONA_USER'), 'password' => getenv('MONA_PASS')]),
    ],
])), true);

if (empty($res['success'])) {
    throw new RuntimeException('Đăng nhập MONA Pay thất bại: ' . ($res['message'] ?? 'không rõ'));
}
$accessToken = $res['data']['access_token']; // lưu lại, dùng 24 giờ

Node

const res = await fetch('https://api.monapay.vn/api/v1/client/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: process.env.MONA_USER, password: process.env.MONA_PASS }),
});
const json = await res.json();
if (!json.success) throw new Error('Đăng nhập MONA Pay thất bại: ' + json.message);
const accessToken = json.data.access_token; // lưu lại, dùng 24 giờ

GET /api/v1/client/me

Thông tin tài khoản đang đăng nhập. Cần Bearer.

curl https://api.monapay.vn/api/v1/client/me \
  -H "Authorization: Bearer $MONA_TOKEN"

Response: data gồm thông tin client (id, username, name, trạng thái kích hoạt, thời điểm tạo).

PUT /api/v1/client/change-password

Đổi mật khẩu của chính mình. Cần Bearer + X-Client-Secret.

curl -X PUT https://api.monapay.vn/api/v1/client/change-password \
  -H "Authorization: Bearer $MONA_TOKEN" \
  -H "X-Client-Secret: $MONA_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"old_password":"MatKhauManh#2026","new_password":"MatKhauMoi#2026"}'

Đổi mật khẩu xong thì token cũ vẫn dùng được tới khi hết hạn; muốn cắt ngay thì đăng nhập lại và thu hồi key ở mục API keys.

Lỗi thường gặp

Bước tiếp theo

1. Tạo API key để có X-Client-Secret.
2. Nối tài khoản ACB, tạo tài khoản ảo.
3. Cấu hình webhook để nhận thông báo tiền vào.