Authentication & Idempotency

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);

import os, uuid, requests

def charge(body: dict, idempotency_key: str):
    headers = {
        'Authorization': f"Bearer {os.environ['FINGO_API_KEY']}",
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotency_key,
    }
    r = requests.post('https://api.fingopay.io/v1/mpesa/charge', json=body, headers=headers)
    return r.json()

key = str(uuid.uuid4())
payload = {
    'phoneNumber': '+254712345678',
    'amount': 150000,
    'merchantTransactionId': 'order_12345',
}
charge(payload, key)
# Retry the same logical request with the same key:
charge(payload, key)

Getting Started

Core Concepts

Release Notes

Authentication & Idempotency

Authentication

Idempotency (required for live POST requests)

​Authentication

​Idempotency (required for live POST requests)

Authentication

Idempotency (required for live POST requests)