Getting Started

This guide will help you quickly get started with integrating our APIs to manage users, counterparties, configure payment instruments, and initiate payments.

Authentication overview

All API requests are secured using a two-step authentication process:

1. Generate a short-lived JWT — Sign a HS256 JWT with your GMA Partner Client ID and Secret ID.
2. Exchange the JWT for a SessionToken — Send the JWT as the x-auth-token header to GET /auth. Use the returned SessionToken as the session-token header on every subsequent request.

Important: All secured calls must originate from the same IP address used when obtaining the SessionToken.

Step 1 — Generate a JWT

The JWT payload must contain exactly three fields:

JavaScript snippet (Node.js — jsonwebtoken)

Install the package once:

npm install jsonwebtoken

npm install jsonwebtoken

Then generate and exchange the JWT:

const jwt = require('jsonwebtoken');

const CLIENT_ID = 'YOUR_GMA_CLIENT_ID';
const CLIENT_SECRET = 'YOUR_GMA_SECRET_ID';

function generateJWT() {
  const iat = Math.floor(Date.now() / 1000);
  return jwt.sign(
    { ClientID: CLIENT_ID, iat, exp: iat + 3000 },
    CLIENT_SECRET,
    { algorithm: 'HS256', noTimestamp: true }
  );
  …

const jwt = require('jsonwebtoken');

const CLIENT_ID = 'YOUR_GMA_CLIENT_ID';
const CLIENT_SECRET = 'YOUR_GMA_SECRET_ID';

function generateJWT() {
  const iat = Math.floor(Date.now() / 1000);
  return jwt.sign(
    { ClientID: CLIENT_ID, iat, exp: iat + 3000 },
    CLIENT_SECRET,
    { algorithm: 'HS256', noTimestamp: true }
  );
  …

JavaScript snippet (Browser / no dependencies)

Uses the native Web Crypto API — no packages needed:

async function generateJWT(clientId, clientSecret) {
  const header  = { alg: 'HS256', typ: 'JWT' };
  const iat     = Math.floor(Date.now() / 1000);
  const payload = { ClientID: clientId, iat, exp: iat + 3000 };

  const b64url = obj =>
    btoa(JSON.stringify(obj))
      .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');

  const message = `${b64url(header)}.${b64url(payload)}`;

  const key = await crypto.subtle.importKey(
  …

async function generateJWT(clientId, clientSecret) {
  const header  = { alg: 'HS256', typ: 'JWT' };
  const iat     = Math.floor(Date.now() / 1000);
  const payload = { ClientID: clientId, iat, exp: iat + 3000 };

  const b64url = obj =>
    btoa(JSON.stringify(obj))
      .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');

  const message = `${b64url(header)}.${b64url(payload)}`;

  const key = await crypto.subtle.importKey(
  …

Step 2 — Call secured endpoints

Once you have a SessionToken, include it as a header on every secured API call:

const sessionToken = await getSessionToken('YOUR_CLIENT_ID', 'YOUR_SECRET');

const res = await fetch('https://sandbox.gma-api.fvbank.us/users', {
  method: 'GET',
  headers: {
    'session-token': sessionToken
  }
});

const data = await res.json();
console.log(data.ResponseData);

const sessionToken = await getSessionToken('YOUR_CLIENT_ID', 'YOUR_SECRET');

const res = await fetch('https://sandbox.gma-api.fvbank.us/users', {
  method: 'GET',
  headers: {
    'session-token': sessionToken
  }
});

const data = await res.json();
console.log(data.ResponseData);

On 401 Unauthorized, re-run the JWT + exchange flow from the same IP address to obtain a fresh SessionToken.

Full integration checklist

1. Authenticate → obtain SessionToken
2. Search or list users → find userId
3. Create a counterparty → counterpartyId
4. Fetch required fields → build CustomValues
5. Create a payment instrument → instrumentId
6. Enable counterparty and instrument
7. Preview the payment → confirm fees
8. Execute the payment → get transactionNumber
9. Poll GET /transactions/{transactionId} → track status

Refer to the API Reference for endpoint details and the other guide sections for workflow-specific steps.