Skip to main content
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

Before you can start integrating, you will need to complete our general onboarding process with the following steps:
  1. Submit Application: Visit fincode.co.uk/contact-us to begin your application.
  2. Provide Documentation: Submit required business documents.
  3. KYC/KYB Verification: Complete the different verification processes.
  4. Compliance Review: Our team will review your application (typically 2-3 days).
  5. 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.
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.
After approval, you’ll have access to two environments:
  • Sandbox: https://{domain}.fincode.software/sandbox
  • Production: https://{domain}.fincode.tech
Log in to your dashboard at your domain to access:
  • 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

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

​
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. 
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",
  }
}

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 -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

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
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
    }
  }
);