MONA Pay API authentication: Bearer token and X-Client-Secret

Every MONA Pay API call needs the header Authorization: Bearer <access_token>. The token comes from POST /api/v1/client/login using the username and password of your my.monapay.vn account and is valid for 86,400 seconds (24 hours). Write calls (POST, PUT, DELETE) add the header X-Client-Secret with a secret generated under API keys. Every response is wrapped in the same envelope {"success": true, "message": "...", "data": ...}.

Base URL

Accounts are usable immediately after sign-up: log in, create an API key, no approval step. A separate sandbox (simulated data, no real bank) is in progress.

Common response envelope

Every endpoint returns the same envelope, including on errors:

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

Validation errors (missing field, wrong type) return HTTP 422 in the FastAPI style with a detail[] list of the offending fields.

Two layers of authentication

Keep the token and the secret in environment variables, never hard-coded, never committed to git.

POST /api/v1/client/register-client

Creates a new account. No authentication. The account is usable immediately; log in right away, no approval. The sign-up form at my.monapay.vn/auth (Sign up tab) calls this same endpoint.

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

Response 200/201:

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

POST /api/v1/client/login

Exchanges username + password for an access_token. No authentication.

Response 200:

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

expires_in is in seconds. When it expires, log in again; there is no refresh token. If the account has 2FA enabled in the dashboard, web login asks for an OTP as well; for direct API calls use an account without 2FA or contact us.

cURL

curl -X POST https://api.monapay.vn/api/v1/client/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"shopabc","password":"StrongPassword#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('MONA Pay login failed: ' . ($res['message'] ?? 'unknown'));
}
$accessToken = $res['data']['access_token']; // keep it, valid for 24 hours

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('MONA Pay login failed: ' + json.message);
const accessToken = json.data.access_token; // keep it, valid for 24 hours

GET /api/v1/client/me

Information about the logged-in account. Needs Bearer.

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

Response: data contains the client record (id, username, name, active status, creation time).

PUT /api/v1/client/change-password

Changes your own password. Needs 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":"StrongPassword#2026","new_password":"NewPassword#2026"}'

After changing the password the old token keeps working until it expires; to cut it off immediately, log in again and revoke the key under API keys.

Common errors

Next steps

1. Create an API key to get X-Client-Secret.
2. Link an ACB account and create virtual accounts.
3. Configure webhooks to receive incoming payments.