Authentication

All Quickvee Pay API requests must be authenticated using API Key + HMAC Signature.

API hosts: sandbox https://api-go-dev.quickveepay.com · production https://api-go.quickveepay.com (details).

Each request requires the following headers:

• X-API-Key
• X-Timestamp
• X-Nonce
• X-Signature

1. X-API-Key

Pass the SHA256 hash of your API key.

X-API-Key: {sha256(API_KEY)}

2. X-Timestamp

Unix timestamp in seconds.

X-Timestamp: {current_unix_timestamp}

const timestamp = Math.floor(Date.now() / 1000);

3. X-Nonce

A unique random string per request to prevent replay attacks.

X-Nonce: {unique_random_string}

const nonce =
  Math.random().toString(36).substring(2, 15) +
  Math.random().toString(36).substring(2, 15);

4. X-Signature

The signature is generated using HMAC-SHA256 over a canonical message.

Signature Rules

You must construct the message exactly as follows:

message = [
  request_method,
  request_path,
  query_params_in_asc_order,
  timestamp,
  nonce,
  payload
].join("\n")

Requirements

• Query params must be sorted alphabetically
• Do not include full URL — only path
• Payload must be:
  • "" for GET
  • JSON.stringify(body) for POST/PUT
• Use newline (\n) separators exactly
• Do not add extra spaces
• Encoding must match exactly on both sides

Generate Signature

signature = HMAC_SHA256(message, API_SECRET_KEY)

X-Signature: {hex_encoded_signature}

Example

const crypto = require("crypto");

// Current timestamp in seconds
const timestamp = Math.floor(Date.now() / 1000);

// Generate nonce
const nonce =
  Math.random().toString(36).substring(2, 15) +
  Math.random().toString(36).substring(2, 15);

// Request details
const method = "GET";
const path = "/api/v1/m/payments";
const query = "limit=10&offset=0&sort_order=-created_at,updated_at";
const payload = ""; // empty for GET (or JSON.stringify(body) for POST)

// Construct message
const message = [
  method,
  path,
  query,
  timestamp,
  nonce,
  payload
].join("\n");

// Secret key
const secretKey = "<some secret key>";

// Generate signature
const signature = crypto
  .createHmac("sha256", secretKey)
  .update(message)
  .digest("hex");

// Headers
const headers = {
  "X-Timestamp": timestamp.toString(),
  "X-Nonce": nonce,
  "X-Signature": signature
};

console.log({ message, headers });

Transport

All requests must use HTTPS. Calls over plain HTTP fail.

Lost or compromised keys

If a key is lost or exposed, contact Quickvee Pay support right away so existing keys can be blocked and replacements issued.

Common authentication errors

Typical 401 responses include:

• Invalid token — The credential is not accepted.
• Invalid timestamp — The timestamp is not valid.
• Invalid signature — The signature is not valid.
• Invalid nonce — The nonce is not valid.

Exact JSON bodies depend on API version; use your environment’s OpenAPI documentation for response schemas.

Next Up

Read Onboard a Business

Questions?

If you're encountering any issues, please reach out to support@quickveepay.com.