API Reference - FinCode Platform

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/

https://{domain}.fincode.tech/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

POST and PUT requests send a JSON body directly. There is no envelope wrapper — pass the fields the endpoint expects at the top level.

Standard Response Structure

All responses use a consistent ResultWrapper envelope:

{
  "status": "SUCCESS",
  "message": "Operation completed successfully",
  "responseCode": 0,
  "errorCode": "0",
  "data": {
    // Response payload (structure varies per endpoint)
  }
}

Field	Type	Description
`status`	String	See status values below
`message`	String	Human-readable description of the result
`responseCode`	Integer	Numeric result code — `0` for success, `-1` for failure
`errorCode`	String	String representation of the result code — `"0"` for success, `"-1"` for failure
`data`	Object	Response payload — structure varies per endpoint

The status field is always one of:

Value	Meaning
`SUCCESS`	Request completed successfully
`FAILED`	Request failed — check `message` for the reason
`ERROR`	An error occurred
`PROCESSING`	Request accepted and still being processed
`PENDING`	Awaiting further action
`PAID`	Payment completed
`CANCEL`	Request was cancelled
`IGNORE`	Request was ignored

Failed responses follow the same envelope:

{
  "status": "FAILED",
  "message": "Detailed error description",
  "responseCode": -1,
  "errorCode": "-1"
}

Error Handling

Most API endpoints return HTTP 200 regardless of outcome and communicate success or failure through the status field in the response body. However, some endpoints — and Spring Security — will return HTTP-level error codes in certain situations.

HTTP Status	When it occurs
`401`	Missing or invalid JWT token — returned by Spring Security before the request reaches the controller
`400`	Bad request — returned by some endpoints on invalid input
`500`	Internal server error — returned by some endpoints on unexpected failures

Always handle both layers — the HTTP status code and the status field in the response body.

Error Handling Example

try {
  const response = await axios.post(url, body, { headers });
  const result = response.data;

  if (result.status === 'FAILED' || result.status === 'ERROR') {
    console.error('Request failed:', result.message);
    throw new Error(result.message);
  }

  // Safe to use result.data
  return result.data;

} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 401:
        // Token missing or expired — refresh and retry
        await refreshToken();
        return makeApiCall();

      case 400:
        console.error('Bad request:', error.response.data);
        throw error;

      case 500:
        console.error('Server error:', error.response.data);
        throw error;

      default:
        console.error('Unexpected 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

Event	Description
`TRANSACTION_STATUS`	Fired when a transaction status changes
`COMPLIANCE_RISK_PROFILE_UPDATED`	Fired after eKYC is processed and a compliance decision is made

Webhook Payload Example

{
  "event-type": "TRANSACTION_STATUS",
  "data": {
    // Event-specific payload
  }
}

Register a callback URL for each event type you want to receive in your pay centre configuration. 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

Test Cards & Bank Accounts

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

​Base URLs

​API Architecture

​Service Categories

Authentication

Transactions

Compliance

Reporting

Revenue Sharing

User Management

​Authentication

​Required Headers

​Example Authenticated Request

​Request & Response Format

​Standard Request Structure

​Standard Response Structure

​Error Handling

​Error Handling Example

​Webhooks

​Webhook Events

​Webhook Payload Example

​SDKs & Libraries

​Coming Soon

JavaScript/TypeScript

Python

PHP

Ruby

​Testing & Sandbox

​Test Data

​Support & Resources

API Status

Support

GitHub

Base URLs

API Architecture

Service Categories

Authentication

Required Headers

Example Authenticated Request

Request & Response Format

Standard Request Structure

Standard Response Structure

Error Handling

Error Handling Example

Webhooks

Webhook Events

Webhook Payload Example

SDKs & Libraries

Coming Soon

Testing & Sandbox

Test Data

Support & Resources