Authentication

To access the APIs, you must first generate a SessionToken. This is done using a two-step process:

Step 1: Generate JWT Create a signed JWT using your ClientID and ClientSecret. This token is short-lived and is used only to authenticate with the /auth endpoint.

Example (Node.js):

const jwt = require('jsonwebtoken');
const clientID = "your_client_id";
const clientSecret = "your_client_secret";
const payload = {
  ClientID: clientID,
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + (60 * 5) // expires in 5 minutes
};
const token = jwt.sign(payload, clientSecret);
console.log("Generated JWT:", token);

Step 2: Get Session Token Send the generated JWT in the X-AUTH-TOKEN header to the /auth endpoint. A SessionToken will be returned in the response.

🔑 Get Session Token (Node.js)

Use your pre-generated JWT to authenticate with the /auth endpoint and receive a SessionToken.

Notes:

• Pass the JWT in the X-AUTH-TOKEN header
• The response will contain a SessionToken
• Use the SessionToken for all subsequent API requests

const axios = require('axios');
// 🔐 Your pre-generated JWT
const JWT_TOKEN = 'your_generated_jwt_token_here';
// 🌐 Base URL
const BASE_URL = 'https://sandbox.merchant.fvbank.us/v2';
async function getSessionToken() {
  try {
    const response = await axios.get(
      `${BASE_URL}/auth`,
      {
        headers: {
  …

Step 3: Use Session Token Send the SessionToken as a Bearer token in the Authorization header for all subsequent API requests:

Authorization: Bearer <SessionToken>

The X-AUTH-TOKEN header is used only on /auth to present your client JWT. Do not send the SessionToken in X-AUTH-TOKEN, and do not prefix the client JWT with Bearer.

Authentication Flow:

Client Credentials → Generate JWT → Call /auth → Receive SessionToken → Use SessionToken for API Calls

Important Notes:

• The client JWT is used only to call /auth. You choose its exp; it does not affect how long the SessionToken lasts
• SessionToken validity is fixed at 15 minutes from the time it is issued, regardless of the exp in your client JWT
• When a request is made within 2 minutes of expiry, the response includes a refreshed token in the x-refresh-token header. Replace your stored SessionToken with that value and keep going — no re-authentication needed
• Always reuse the SessionToken until it expires
• Regenerate token if you receive authentication errors (401)
• Requests must originate from the same IP used during authentication