Authentication

Chargeflow provides a REST API that enables you to programmatically view and update data in your Chargeflow account, and receive event notifications via Webhooks.

Overview

Chargeflow uses API key authentication. Every request must include your x-api-key header. Optionally, you can enable HMAC signature validation to add a second layer of security that guarantees both the integrity and authenticity of your requests.

Required credentials:

• API Access Key: included in the x-api-key header on every request.
• API Secret Key: only needed if HMAC signature validation is enabled.

Generate your keys in the Chargeflow App under Settings → Developers → Generate Keys - see API keys for the full walkthrough and how to use them. Any active Chargeflow account can generate a key: there is no plan requirement and no approval step.

Where the key belongs

One key pair covers both directions of the integration. The Access Key authenticates the REST calls you make, and generating it is also what unlocks webhook registration, where the Secret Key is used to sign the deliveries Chargeflow sends you (see Webhooks). So the key is not "just for webhooks".

Use it wherever your own code or automation calls Chargeflow: your backend, a Zapier connection, or your CRM's outbound HTTP step. It is not entered in your payment processor's portal, and it must never appear in client-side code.

HMAC signature validation (optional)

By default, HMAC signature verification is disabled on newly generated access keys. In this mode, the API key alone authenticates your requests, making it easy to integrate in your codebase or in tools like Zapier or Make.

If you prefer an additional layer of security, ensuring data integrity (no tampering) and authenticity (requests come from you), you can enable HMAC Signature Validation in the Developers section of your Chargeflow settings.

Once enabled, Chargeflow's servers will always verify the HMAC signature of your incoming requests.

Code examples

const crypto = require('crypto')

// Function to generate HMAC-SHA256 signature
function generateHmacSignature(data, secretKey) {
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(data);
  return hmac.digest('hex');
}

function calculateHmac(method, path, body, secretKey) {
  // Example request data
  const requestData = {
    method: method.toUpperCase(),
    path,
    body,
  };

  // Compose string to sign from request data
  const dataToSign = `${requestData.method}\n${requestData.path}\n${requestData.body}`;

  // Generate HMAC signature
  const hmacSignature = generateHmacSignature(dataToSign, secretKey);
  return hmacSignature;
}

// Example request data
const method = 'POST';
const path = '/public/2025-04-01/disputes/dispute-id/subscription';
// # Example request body. Work with the same string when sending to ensure that body is sent exactly as signed.
const body = JSON.stringify({ param: 'value' });

// Calculate HMAC signature
const secretKey = 'your-secret-key';
const hmacSignature = calculateHmac(method, path, body, secretKey);

console.log('Generated HMAC-SHA256 Signature:', hmacSignature);

// You can now use the generated signature as the 'x-chargeflow-hmac-sha256' header value

Next steps