Quick Start Guide

Get started with FinCode’s multitenant platform in three simple steps. This guide will walk you through account setup, authentication, and making your first API call.

Step 1: Account Setup & Due Diligence

Complete Due Diligence

Before you can start integrating, you will need to complete our general onboarding process with the following steps:

Submit Application: Visit fincode.co.uk/contact-us to begin your application.
Provide Documentation: Submit required business documents.
KYC/KYB Verification: Complete the different verification processes.
Compliance Review: Our team will review your application (typically 2-3 days).
Account Approval: Receive approval notification with your sandbox details.

Have your business registration documents, proof of address, and compliance certificates ready to speed up the process.

Get Your Credentials

Once approved, you’ll receive your unique sandbox credentials:

Your Domain Format

https://{domain}.fincode.software

Your domain is your dedicated environment where all your API calls will be made. This ensures complete tenant isolation and data security.

Your domain will be provided in your approval email. Keep this information secure as it’s required for all API requests.

Access Your Sandbox

After approval, you’ll have access to two environments:

Sandbox: https://{domain}.fincode.software/sandbox
Production: https://{domain}.fincode.tech

API documentation specific to your tenant
Sandbox test data and accounts
Configuration settings
Webhook management
Analytics and reporting

Always test thoroughly in sandbox before moving to production.

Step 2: Generate API Tokens

Two ways to generate a token

Populate Login Details and login through the API
Generate a token for selected environment or service on your dashboard

Token Security Best Practices

Protecting Your Tokens

Never commit tokens to version control
Use environment variables for token storage
Rotate tokens every 90 days or when compromised
Use least-privilege principle - only grant necessary permissions
Monitor token usage in your dashboard

Environment Variables Setup

# Add to your .env file
DOMAIN=domain
JWT_ACCESS_TOKEN=fct_sandbox_your_token_here
FINCODE_BASE_URL=https://{domain}.fincode.software

If you suspect a token has been compromised, revoke it immediately from your dashboard.

Step 3: Make Your First API Call

Test your authentication by logging in via API. This will verify your setup and return an access token for subsequent requests.

Node.js Example

const axios = require('axios');

const DOMAIN = process.env.DOMAIN;
const JWT_ACCESS_TOKEN = process.env.JWT_ACCESS_TOKEN;
const BASE_URL = `https://${DOMAIN}.fincode.software`;

async function login() {
  try {
    const response = await axios.put(
      `${BASE_URL}/api/v6/services/securitymanagement/login`,
      {
        email: 'your-email@company.com',
        currentPassword: 'your-password'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'uuid': 200,
          'platform': 'fincode'
        }
      }
    );

    console.log('Login successful!');
    console.log('Access Token:', response.data.token);

    return response.data;
  } catch (error) {
    console.error('Login failed:', error.response?.data || error.message);
    throw error;
  }
}

login()
  .then(data => {
    const accessToken = data.access_token;
    console.log('Ready to make API calls!');
  })
  .catch(err => {
    console.error('Authentication error:', err);
  });

Expected Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "modules": ["REMITTANCE", "LENDING"],
  "country": "Nigeria",
  "expires_in": 3600,
  "organisation": "def50200a1b2c3d4e5f6...",
  "profileDetailsResponseDTO": {
    "phone": "448182147656",
    "dob": "1994-02-24",
    "email": "your-email@company.com",
    "userType": "REGISTERED_CUSTOMER",
    "id": "8ecca811-607f-44e1-a57e-cd856c50437d",
    "accessScope": "CUSTOMER_FLOW",
  }
}

Java Example

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import com.google.gson.Gson;
import com.google.gson.JsonObject;

public class FinCodeAuth {
    private static final String DOMAIN = System.getenv("DOMAIN");
    private static final String JWT_ACCESS_TOKEN = System.getenv("JWT_ACCESS_TOKEN");
    private static final String BASE_URL = String.format(
        "https://%s.fincode.software",
        DOMAIN
    );

    public static class LoginResponse {
        public String token;
        public String role;
        public int currencyCode;
        public String twoFactorEnabled;
        public String organisation;
        public ProfileDetailsResponseDTO user;

        public static class User {
            public String id;
            public String firstName;
            public String lastName;
            public String phone;
        }
    }

    public static LoginResponse login(String email, String currentPassword) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        Gson gson = new Gson();

        JsonObject requestBody = new JsonObject();
        requestBody.addProperty("email", email);
        requestBody.addProperty("currentPassword", currentPassword);

        // Build request
            .uri(URI.create(BASE_URL + "/api/v6/services/securitymanagement/login"))
            .header("Content-Type", "application/json")
            .header("uuid", "200")
            .header("platform", "fincode")
            .PUT(BodyPublishers.ofString(gson.toJson(requestBody)))
            .build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() == 200) {
            System.out.println("Login successful!");
            LoginResponse loginResponse = gson.fromJson(
                response.body(),
                LoginResponse.class
            );

            System.out.println("Access Token: " + loginResponse.token);

            return loginResponse;
        } else {
            throw new Exception("Login failed: " + response.body());
        }
    }

    public static void main(String[] args) {
        try {
            LoginResponse response = login(
                "your-email@company.com",
                "your-password"
            );

            String accessToken = response.token;
            System.out.println("Ready to make API calls!");

        } catch (Exception e) {
            System.err.println("Authentication error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

cURL Example

curl -X PUT "https://{domain}.fincode.software/api/v6/services/securitymanagement/login" \
  -H "Content-Type: application/json" \
  -H "uuid: 200" \
  -H "platform: fincode" \
  -d '{
    "email": "your-email@company.com",
    "currentPassword": "your-password"
  }'

Next Steps

Now that you’re authenticated, choose your product to continue:

Remittance

Create beneficiary
Get FX quote
Send transaction

Digital Lending

Create customer
Submit application
Check decision

Investment

Create account
Add portfolio
Execute trades

Common Issues & Troubleshooting

Authentication Errors

401 Unauthorized

Verify your API token is correct and not expired
Ensure you’re using the correct domain
Check that your token has the necessary permissions

403 Forbidden

Your account may not have access to the requested resource
Contact support to verify your tenant permissions

Token Expiration

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

const response = await axios.post(
  `${BASE_URL}/api/v6/services/securitymanagement/refresh`,
  {
    refresh_token: refreshToken
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'X-API-Token': JWT_ACCESS_TOKEN
    }
  }
);

Need Help?

Documentation: Browse our API Reference
Support: Email hello@fincode.co.uk
System Status: Check status.fincode.com
Community: Visit our GitHub for examples

Getting Started

Core Concepts

Integration

Step 1: Account Setup & Due Diligence

Your Domain Format

Step 2: Generate API Tokens

Protecting Your Tokens

Environment Variables Setup

Step 3: Make Your First API Call

Next Steps

Remittance

Digital Lending

Investment

Common Issues & Troubleshooting

​Step 1: Account Setup & Due Diligence

​Your Domain Format

​Step 2: Generate API Tokens

​Protecting Your Tokens

​Environment Variables Setup

​Step 3: Make Your First API Call

​Next Steps

Remittance

Digital Lending

Investment

​Common Issues & Troubleshooting

Step 1: Account Setup & Due Diligence

Your Domain Format

Step 2: Generate API Tokens

Protecting Your Tokens

Environment Variables Setup

Step 3: Make Your First API Call

Next Steps

Common Issues & Troubleshooting