Skip to main content
Our REST API provides programmatic access to all FinCode services including remittance, digital lending, and investment operations.
All API endpoints require authentication using JWT tokens. Make sure you’ve completed the authentication setup before making API calls.

​
Base URLs

Your API base URL depends on your tenant domain and environment: 
https://{domain}.fincode.software/api/v6/services/
Always test your integration thoroughly in the sandbox environment before deploying to production.

​
API Architecture

The FinCode API is organized into service-based endpoints following a RESTful architecture: 
/api/v6/services/{service-name}/{resource}

​
Service Categories

Authentication

User authentication, token management, and session handling

Transactions

Remittance, and virtual wallet transaction processing

Compliance

KYC/AML verification, sanctions screening, and regulatory compliance

Reporting

Analytics, transaction reports, and business intelligence

Revenue Sharing

Commission management, partner payouts, and revenue distribution

User Management

Create and manage managers, agents, cashiers, and customers

​
Authentication

All API requests must include authentication headers otherwise stated:

​
Required Headers

{
  "X-Auth-Token": "your_jwt_access_token",
  "Content-Type": "application/json",
  "platform": "fincode",
  "uuid": "200"
}

​
Example Authenticated Request

const axios = require('axios');

const response = await axios.get(
  'https://your-company.fincode.software/api/v6/services/admin/organisation-preference-management/fetch-organisation-preference',
  {
    headers: {
      'X-Auth-Token': process.env.JWT_ACCESS_TOKEN,
      'Content-Type': 'application/json',
      platform: 'fincode',
      uuid: '200',
    },
  }
);
Store your JWT tokens securely and implement automatic token refresh to maintain uninterrupted API access.

​
Request & Response Format

​
Standard Request Structure

All POST and PUT requests follow this structure: 
{
  "data": {
    // Request payload
  },
  "metadata": {
    "request_id": "unique_request_identifier",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Standard Response Structure

Successful responses (HTTP 200-299): 
{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "request_id": "unique_request_identifier",
    "timestamp": "2024-01-15T10:30:00Z",
    "processing_time_ms": 145
  }
}
Error responses (HTTP 400-599): 
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Detailed error message",
    "field": "specific_field_name",
    "details": {}
  },
  "metadata": {
    "request_id": "unique_request_identifier",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Error Codes

​
Common Error Codes

CodeHTTP StatusDescription
AUTH_REQUIRED401Missing or invalid authentication token
FORBIDDEN403Insufficient permissions for this operation
NOT_FOUND404Resource not found
VALIDATION_ERROR422Request validation failed
RATE_LIMIT_EXCEEDED429Too many requests
SERVER_ERROR500Internal server error
SERVICE_UNAVAILABLE503Service temporarily unavailable

​
Error Handling Example

try {
  const response = await makeApiCall();
  return response.data;
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 401:
        // Refresh token and retry
        await refreshToken();
        return makeApiCall();

      case 429:
        // Wait and retry with exponential backoff
        await sleep(error.response.headers['retry-after'] * 1000);
        return makeApiCall();

      case 422:
        // Handle validation errors
        console.error('Validation failed:', error.response.data.error);
        throw error;

      default:
        console.error('API error:', error.response.data);
        throw error;
    }
  }
  throw error;
}

​
Webhooks

FinCode can notify your application of events via webhooks. Configure webhook endpoints in your dashboard.

​
Webhook Events

  • transaction.created
  • transaction.completed
  • transaction.failed
  • kyc.verification.completed
  • loan.approved
  • loan.disbursed
  • payment.received

​
Webhook Payload Example

{
  "event": "transaction.completed",
  "event_id": "evt_123456",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "transaction_id": "txn_789012",
    "status": "completed",
    "amount": 1000.0,
    "currency": "USD"
  },
  "signature": "sha256_signature_for_verification"
}
Learn more about webhooks →

​
SDKs & Libraries

Official SDKs are currently in development. We’ll support JavaScript/TypeScript, Python, PHP, and Ruby in the near future. For now, you can use standard HTTP clients like axios, fetch, or requests to integrate with our API.

​
Coming Soon

JavaScript/TypeScript

Node.js and browser support with full TypeScript definitions

Python

Pythonic API with async/await support

PHP

PSR-compliant library for PHP 7.4+

Ruby

Ruby gem with Rails integration

​
Testing & Sandbox

Use the sandbox environment for testing without affecting production data:
  • URL: https://{domain}.fincode.software/api/v6/services/
  • Data: All transactions are simulated
  • Webhooks: Webhook events are generated but not processed

​
Test Data

Use these test credentials in sandbox:Test Bank Account
{
  "account_number": "8883633074",
  "bank_code": "044",
  "account_name": "VICTOR ADEBIYI"
}
Test Card
{
  "card_number": "4111 1111 1111 1111",
  "expiry": "12/27",
  "cvv": "123"
}

​
Support & Resources

API Status

Real-time system status

Support

Technical support team

GitHub

Code examples & samples