​
Authentication

Use your API key as a Bearer token in the Authorization header for every request. 
Authorization: Bearer <YOUR_SECRET_KEY>
  • All requests must use HTTPS (TLS 1.2+). Requests made over HTTP are rejected.
  • Keep your secret keys secure and do not embed them in client-side code or mobile apps.
  • We return a per-request X-Request-Id you can reference when contacting support.
Never expose your secret API key in client-side code or mobile apps.

​
Idempotency (recommended for POST)

To safely retry POST requests without duplicating operations, send a unique key: 
Idempotency-Key: <a-unique-uuid-per-merchantTransactionId>
  • Tie the idempotency key to your merchantTransactionId.
  • Repeating a POST with the same key returns the original response as long as the method, path, and body are identical.
  • Conflicting retries (same key but different body) return 409 conflict.
import crypto from 'node:crypto'

async function charge(body) {
  const idempotencyKey = crypto.randomUUID();
  const res = await fetch('https://api.fingopay.io/v1/mpesa/charge', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FINGO_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify(body)
  });
  return res.json();
}