Skip to main content

​
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 (required for live POST requests)

To safely retry POST requests without duplicating operations, send an idempotency key: 
Idempotency-Key: <a-unique-uuid-per-merchantTransactionId>
  • Tie the idempotency key to your merchantTransactionId.
  • Reuse the exact same idempotency key when retrying the same logical request.
  • Repeating a POST with the same key returns the original response as long as 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, idempotencyKey) {
  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();
}

const idempotencyKey = crypto.randomUUID();
await charge({ phoneNumber: '+254712345678', amount: 150000, merchantTransactionId: 'order_12345' }, idempotencyKey);
// If you retry the same request, reuse the same key:
await charge({ phoneNumber: '+254712345678', amount: 150000, merchantTransactionId: 'order_12345' }, idempotencyKey);