Authentication

API Authentication

FossaPay uses API keys to authenticate requests. You can view and manage your API keys in the FossaPay Dashboard.

Production only. FossaPay currently uses production systems for every API request, so keep your live API keys secure and only test with amounts and actions you are comfortable running against production.

API Key Types

FossaPay currently provides live production API keys:

Live Keys

Use live keys to authenticate production requests and manage real customer data.

Getting Your API Keys

Sign up or log in to your FossaPay Dashboard
Navigate to Settings → API Keys
Copy your Live Key
Use the live key for all API requests

Making Authenticated Requests

Include your secret key in the x-api-key header of your API requests:

curl https://api-production.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: fk_production_DTKUG..." \
  -H "Content-Type: application/json"

Authentication Header Format

x-api-key: fk_production_DTKUG...

API Key Format

FossaPay API keys follow this format:

Production Key: fk_production_DTKUG...

Request Headers

Every API request should include these headers:

Header	Value	Required
`x-api-key`	`fk_production_DTKUG...`	Yes
`Content-Type`	`application/json`	Yes
`X-Idempotency-Key`	Unique request identifier	Recommended

Example Request

const axios = require('axios');

const response = await axios.post(
  'https://api-production.fossapay.com/api/v1/wallets/fiat/create',
  {
    customerId: 'cus_123456789',
    walletName: 'Main Wallet',
    walletReference: 'wallet_ref_001'
  },
  {
    headers: {
      'x-api-key': 'fk_production_DTKUG...',
      'Content-Type': 'application/json',
      'X-Idempotency-Key': 'unique-request-id-12345'
    }
  }
);

Idempotency

To prevent duplicate requests, use the X-Idempotency-Key header. If you make the same request twice with the same idempotency key, FossaPay will return the same response without processing the request again.

curl https://api-production.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: fk_production_DTKUG..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: payout-20240119-001" \
  -d '{
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationBankCode": "044",
    "destinationAccountName": "JOHN DOE",
    "destinationAccountNumber": "1234567890",
    "destinationBankName": "ACCESS BANK",
    "reference": "TRF-2024-001",
    "remarks": "Salary payment",
    "amount": 10000
  }'

Use idempotency keys for all POST requests, especially for payouts, to prevent accidental duplicate transactions.

Error Handling

Authentication Errors

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "success": false,
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Common authentication errors:

Error Code	Description
`INVALID_API_KEY`	The API key provided is invalid
`EXPIRED_API_KEY`	The API key has expired
`MISSING_API_KEY`	No API key was provided

Security Best Practices

Store Keys Securely

Never hardcode API keys in your application
Use environment variables or secure key management systems
Rotate keys regularly

Use HTTPS Only

All API requests must use HTTPS
HTTP requests will be rejected

Restrict API Key Access

Limit API key permissions to only what’s needed
Use different keys for different applications or services
Monitor API key usage in your dashboard

Implement Rate Limiting

FossaPay implements rate limiting to protect against abuse
Current limit: 100 requests per minute
Contact support for higher limits

Verifying Authentication

Verify your authentication setup with this simple request:

curl https://api-production.fossapay.com/api/v1/customers \
  -H "x-api-key: fk_production_DTKUG..."

Successful Response:

{
  "success": true,
  "message": "List of customers retrieved successfully",
  "data": []
}

Next Steps

Create a Customer

Make your first API call

Getting Started

Core Concepts

Guides

AI Tools

API Authentication

API Key Types

Live Keys

Getting Your API Keys

Making Authenticated Requests

Authentication Header Format

API Key Format

Request Headers

Example Request

Idempotency

Error Handling

Authentication Errors

Security Best Practices

Verifying Authentication

Next Steps

Create a Customer

​API Authentication

​API Key Types

Live Keys

​Getting Your API Keys

​Making Authenticated Requests

​Authentication Header Format

​API Key Format

​Request Headers

​Example Request

​Idempotency

​Error Handling

​Authentication Errors

​Security Best Practices

​Verifying Authentication

​Next Steps

Create a Customer

API Authentication

API Key Types

Getting Your API Keys

Making Authenticated Requests

Authentication Header Format

API Key Format

Request Headers

Example Request

Idempotency

Error Handling

Authentication Errors

Security Best Practices

Verifying Authentication

Next Steps