Authentication

Every request to the TagPay API (except merchant registration) requires a valid access token. This page explains how to get a token, how to use it, when it expires, and how to handle expiry gracefully.

Get an access token

Call POST /auth/login with your merchant account email and password. The API returns tokens in response headers, not in the response body.

POST https://api.tagpay.ng/v1/auth/login

The email and password values must be Base64-encoded before sending. The server decodes them server-side before validation. Example: Buffer.from("[email protected]").toString("base64") in Node.js, or echo -n "[email protected]" | base64 in bash.

Request

string

required

Your merchant account email address, Base64-encoded.

string

required

Your account password (minimum 6 characters), Base64-encoded.

object

Optional device context for audit logging. Useful for identifying sessions.

Show metadata fields

string

A unique fingerprint for the device making the request. Maximum 255 characters.

string

A stable identifier for the device. Maximum 255 characters.

string

The device timezone, e.g. Africa/Lagos. Maximum 100 characters.

string

The device locale, e.g. en-NG. Maximum 20 characters.

# Base64-encode your credentials first:
# echo -n "[email protected]" | base64   →  YWRhQGV4YW1wbGUuY29t
# echo -n "securepassword" | base64    →  c2VjdXJlcGFzc3dvcmQ=

curl -X POST https://api.tagpay.ng/v1/auth/login \
  -H "Content-Type: application/json" \
  -D - \
  -d '{
    "email": "YWRhQGV4YW1wbGUuY29t",
    "password": "c2VjdXJlcGFzc3dvcmQ="
  }'

const email = Buffer.from("[email protected]").toString("base64");
const password = Buffer.from("securepassword").toString("base64");

const response = await fetch("https://api.tagpay.ng/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password }),
});

const accessToken = response.headers.get("X-Access-Token");
const refreshToken = response.headers.get("X-Refresh-Token");
const data = await response.json();

Response

The access and refresh tokens are in the response headers.

Header	Description
`X-Access-Token`	Bearer token to include on all subsequent requests
`X-Refresh-Token`	Token used to generate a new access token when the current one expires

Response body

{
  "status": true,
  "data": {
    "id": "usr_01hw...",
    "role": "MERCHANT",
    "email": "[email protected]",
    "firstName": "Ada",
    "lastName": "Obi",
    "mode": "SANDBOX",
    "createdAt": "2026-04-08T10:00:00.000Z",
    "updatedAt": "2026-04-08T10:00:00.000Z"
  },
  "merchant": {
    "id": "mer_01hw..",
    "businessName": "Ada Ventures",
    "businessType": "FINANCIAL-SERVICES",
    "mode": "SANDBOX",
    "review": "PENDING",
    "owner": true,
    "role": "MERCHANT",
    "callbackURL": null,
    "sandboxCallbackURL": null,
    "parentMerchant": null,
    "canDebitCustomer": false
  },
  "availableMerchants": [],
  "hasMultipleMerchants": false
}

If your account has not been verified, the login response will include "requiresVerification": true and the API will send a new verification code to your email. Verify your account using PUT /merchant/verify before attempting to log in again.

Authenticate requests

Include the access token in the Authorization header on every request:

Authorization: Bearer <your-access-token>

curl -X GET https://api.tagpay.ng/v1/merchant/wallet \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch("https://api.tagpay.ng/v1/merchant/wallet", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

Refresh your token

Access tokens expire. When a request returns 401 Unauthorized, use your refresh token to obtain a new token pair without asking the user to log in again.

POST https://api.tagpay.ng/v1/auth/refresh/token

Pass the refresh token in the X-Refresh-Token request header (not in the body).

curl -X POST https://api.tagpay.ng/v1/auth/refresh/token \
  -H "X-Refresh-Token: d4f9a2c1e8b3..."

async function refreshAccessToken(refreshToken) {
  const response = await fetch("https://api.tagpay.ng/v1/auth/refresh/token", {
    method: "POST",
    headers: { "X-Refresh-Token": refreshToken },
  });

  const newAccessToken = response.headers.get("X-Access-Token");
  const newRefreshToken = response.headers.get("X-Refresh-Token");

  return { newAccessToken, newRefreshToken };
}

The API rotates the token pair on every refresh. Store the new X-Access-Token and X-Refresh-Token from the response headers and discard the old ones. Response headers (on success)

X-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Refresh-Token: a1b2c3d4e5f6...

Each refresh token can only be used once. Once you call /auth/refresh/token, the previous token pair is invalidated. If your refresh token is expired or invalid, the user must log in again.

Automatic token refresh in Node.js

class TagPayClient {
  constructor({ accessToken, refreshToken }) {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
  }

  async request(url, options = {}) {
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${this.accessToken}`,
      },
    });

    if (response.status === 401) {
      // Token expired — refresh and retry once
      const refreshed = await fetch("https://api.tagpay.ng/v1/auth/refresh/token", {
        method: "POST",
        headers: { "X-Refresh-Token": this.refreshToken },
      });

      if (!refreshed.ok) throw new Error("Session expired. Please log in again.");

      this.accessToken = refreshed.headers.get("X-Access-Token");
      this.refreshToken = refreshed.headers.get("X-Refresh-Token");

      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${this.accessToken}`,
        },
      });
    }

    return response;
  }
}

Access keys (for webhook signing)

In addition to your access token, TagPay gives you a public key and private key for your merchant account. These are used to sign and verify webhook payloads — they are not used for API authentication.

Get your access keys

GET https://api.tagpay.ng/v1/merchant/my-access-keys

curl -X GET https://api.tagpay.ng/v1/merchant/my-access-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch("https://api.tagpay.ng/v1/merchant/my-access-keys", {
  headers: { Authorization: `Bearer ${accessToken}` },
});

const { data } = await response.json();
console.log("Public key:", data.publicKey);
console.log("Private key:", data.privateKey);

Response

{
  "status": true,
  "data": {
    "publicKey": "pk_sandbox_...",
    "privateKey": "sk_sandbox_..."
  }
}

Your private key is sensitive. Do not expose it in client-side code or commit it to version control. Store it as an environment variable or in a secrets manager.

Rotate your access keys

If your private key is compromised, generate a new key pair immediately. The old key pair is invalidated as soon as you generate new ones.

POST https://api.tagpay.ng/v1/merchant/generate-access-keys

curl -X POST https://api.tagpay.ng/v1/merchant/generate-access-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const response = await fetch("https://api.tagpay.ng/v1/merchant/generate-access-keys", {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}` },
});

const { data } = await response.json();
// Update your stored keys immediately

Response

{
  "status": true,
  "data": {
    "publicKey": "pk_sandbox_new...",
    "privateKey": "sk_sandbox_new..."
  }
}

Common authentication errors

Status	Code	Meaning
`401`	`UNAUTHORIZED`	The access token is missing, expired, or invalid. Refresh the token or log in again.
`403`	`FORBIDDEN`	The token is valid but your account does not have permission for this action. Check that your account is active and has the required role.
`400`	`ACCOUNT_LOCKED`	Your merchant account has been locked from login. Contact TagPay support to resolve this.

Always check for a 401 response in your HTTP client and implement automatic token refresh. Users should never see an authentication error if your refresh logic is in place.

Get Started

Core Concepts

Guides

Get an access token

Request

Response

Authenticate requests

Refresh your token

Automatic token refresh in Node.js

Access keys (for webhook signing)

Get your access keys

Rotate your access keys

Common authentication errors

​Get an access token

​Request

​Response

​Authenticate requests

​Refresh your token

​Automatic token refresh in Node.js

​Access keys (for webhook signing)

​Get your access keys

​Rotate your access keys

​Common authentication errors

Get an access token

Request

Response

Authenticate requests

Refresh your token

Automatic token refresh in Node.js

Access keys (for webhook signing)

Get your access keys

Rotate your access keys

Common authentication errors