Skip to main content

​
API Authentication

FossaPay uses API keys to authenticate requests. You can view and manage your API keys in the FossaPay Dashboard.
Keep your API keys secure! Your secret keys can perform any API request without restriction. Keep them secure and never share them publicly or commit them to version control.

​
API Key Types

FossaPay provides two types of API keys:

Test Keys

Use test keys in sandbox mode to test your integration without affecting real data or transactions.

Live Keys

Use live keys in production to process real transactions and manage actual customer data.

​
Getting Your API Keys

  1. Sign up or log in to your FossaPay Dashboard
  2. Navigate to Settings → API Keys
  3. Copy your Test Key or Live Key
  4. Use the test keys for development and live keys for production

​
Making Authenticated Requests

Include your secret key in the x-api-key header of your API requests: 
curl https://api-staging.fossapay.com/api/v1/wallets/fiat/create \
  -H "x-api-key: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

​
Authentication Header Format

x-api-key: fp_live_1234567890abcdef

​
API Key Format

FossaPay API keys follow this format:
  • Test Key: fp_test_sk_xxxxxxxxxxxxxxxx
  • Live Key: fp_live_sk_xxxxxxxxxxxxxxxx

​
Request Headers

Every API request should include these headers:
HeaderValueRequired
x-api-keyYOUR_SECRET_KEYYes
Content-Typeapplication/jsonYes
X-Idempotency-KeyUnique request identifierRecommended

​
Example Request

const axios = require('axios');

const response = await axios.post(
  'https://api-staging.fossapay.com/api/v1/wallets/fiat/create',
  {
    customerId: 'cus_123456789',
    walletName: 'Main Wallet',
    walletReference: 'wallet_ref_001'
  },
  {
    headers: {
      'x-api-key': 'fp_test_sk_xxxxxxxxxxxxxxxx',
      '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-staging.fossapay.com/api/v1/transfers/fiat/inter-bank \
  -H "x-api-key: YOUR_SECRET_KEY" \
  -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 CodeDescription
INVALID_API_KEYThe API key provided is invalid
EXPIRED_API_KEYThe API key has expired
MISSING_API_KEYNo API key was provided
TEST_KEY_IN_PRODUCTIONAttempted to use test key in live mode
LIVE_KEY_IN_TESTAttempted to use live key in test mode

​
Security Best Practices

  • Never hardcode API keys in your application
  • Use environment variables or secure key management systems
  • Rotate keys regularly
  • All API requests must use HTTPS
  • HTTP requests will be rejected
  • Limit API key permissions to only what’s needed
  • Use different keys for different environments
  • Monitor API key usage in your dashboard
  • FossaPay implements rate limiting to protect against abuse
  • Current limit: 100 requests per minute
  • Contact support for higher limits

​
Testing Authentication

Test your authentication setup with this simple request: 
curl https://api-staging.fossapay.com/api/v1/customers \
  -H "x-api-key: YOUR_SECRET_KEY"
Successful Response: 
{
  "success": true,
  "message": "List of customers retrieved successfully",
  "data": []
}

​
Next Steps

Create a Customer

Make your first API call