GP CoreBanking API

Complete API documentation for external integrations

Introduction

The GP CoreBanking API provides a comprehensive set of endpoints for integrating with our banking system. The API implements a full double-entry accounting system for all financial transactions, ensuring data integrity and complete audit trails.

Key Features

  • Double-Entry Accounting - All financial transactions follow double-entry accounting principles
  • Client Management - APIs for creating and managing both retail and corporate clients
  • Account Management - Support for multiple account types including Savings, Checking, Current, and Loan accounts
  • Transaction Processing - Secure handling of deposits, withdrawals, and transfers
  • Data Integrity - Database transactions ensure atomicity of all operations

Base URL

All API requests should be prefixed with the following base URL:

https://bkclatwirugxogrfbhno.supabase.co/functions/v1/corebanking

Health Check

A root endpoint is available for health checks:

GET /

Example Response:

{
  "status": "success",
  "message": "Core Banking API is running",
  "apiVersion": "1.0.0"
}

Implementation Notes

  • The API uses Supabase as the database backend
  • System accounts (Teller, Vault) are automatically created if they don't exist
  • For deposits and withdrawals, the system ensures that all transactions are balanced across the customer account, teller account, and vault account
  • Account numbers are automatically generated with prefixes based on account type (SAV, CHK, CUR, LOA)

Authentication

All API endpoints require authentication with a JWT token.

Example Request with Authentication

Include the JWT token in the Authorization header:

curl -X GET "https://bkclatwirugxogrfbhno.supabase.co/functions/v1/corebanking/clients" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json"

API Endpoints

Client Management

GET /clients

Retrieve a list of all clients.

Query Parameters:
  • client_type (optional) - Filter by client type ("Retail" or "Corporate")
  • ussd_phone (optional) - Filter by USSD phone number (for Retail clients only)
View Example Response 
{
  "status": "success",
  "data": [
    {
      "client_id": "123",
      "client_type": "Retail",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "contact_number": "1234567890",
      "address": "123 Main St",
      "ussd_phone_number": "0233456789",
      "ussd_status": "active",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    },
    {
      "client_id": "456",
      "client_type": "Corporate",
      "company_name": "ABC Corp",
      "registration_number": "ABC123",
      "email": "contact@abc.com",
      "contact_number": "0987654321",
      "address": "456 Business Ave",
      "created_at": "2023-01-02T00:00:00Z",
      "updated_at": "2023-01-02T00:00:00Z"
    }
  ]
}

GET /clients/:client_id

Retrieve details of a specific client.

Path Parameters:
  • client_id - Unique identifier of the client
View Example Response 
{
  "status": "success",
  "data": {
    "client_id": "123",
    "client_type": "Retail",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "contact_number": "1234567890",
    "address": "123 Main St",
    "ussd_phone_number": "0233456789",
    "ussd_status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

GET /clients/ussd/search

Search for a retail client by their USSD phone number.

Query Parameters:
  • ussd_phone (required) - USSD phone number to search for
View Example Response 
{
  "status": "success",
  "data": {
    "client_id": "123",
    "client_type": "Retail",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "contact_number": "1234567890",
    "address": "123 Main St",
    "ussd_phone_number": "0233456789",
    "ussd_status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

POST /clients

Create a new client.

Request Body:
  • For Retail Clients 
    {
  "client_type": "Retail",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "contact_number": "1234567890",
  "address": "123 Main St",
  "ussd_phone_number": "0233456789",
  "ussd_status": "active"
}
  • For Corporate Clients 
    {
  "client_type": "Corporate",
  "company_name": "ABC Corp",
  "registration_number": "ABC123",
  "email": "contact@abc.com",
  "contact_number": "0987654321",
  "address": "456 Business Ave"
}
View Example Response 
{
  "status": "success",
  "data": {
    "client_id": "123",
    "client_type": "Retail",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "contact_number": "1234567890",
    "address": "123 Main St",
    "ussd_phone_number": "0233456789",
    "ussd_status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

Account Management

GET /accounts

Retrieve a list of accounts.

Query Parameters:
  • client_id (optional) - Filter by client ID
  • account_type (optional) - Filter by account type ("Savings", "Checking", "Current", "Loan")
  • status (optional) - Filter by status ("Active", "Inactive", "Frozen")
  • currency (optional) - Filter by currency code
View Example Response 
{
  "status": "success",
  "data": [
    {
      "account_id": "acc123",
      "client_id": "123",
      "account_number": "SAV-1234567890",
      "account_type": "Savings",
      "currency": "GHS",
      "balance": 1000,
      "status": "Active",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ]
}

GET /accounts/:account_id

Retrieve details of a specific account.

Path Parameters:
  • account_id - Unique identifier of the account
View Example Response 
{
  "status": "success",
  "data": {
    "account_id": "acc123",
    "client_id": "123",
    "account_number": "SAV-1234567890",
    "account_type": "Savings",
    "currency": "GHS",
    "balance": 1000,
    "status": "Active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

GET /accounts/number/:accountNumber/balance

Retrieve the balance of a specific account using its account number.

Path Parameters:
  • accountNumber - The unique account number of the account
View Example Success Response (200 OK) 
{
  "status": "success",
  "data": {
    "account_id": "acc456",
    "account_number": "CHK-0987654321",
    "balance": 2500.75,
    "currency": "GHS"
  }
}
View Example Error Response (404 Not Found) 
{
  "status": "error",
  "message": "Account with number CHK-0000000000 not found"
}
View Example Error Response (500 Internal Server Error) 
{
  "status": "error",
  "message": "An error occurred while fetching account balance"
}

POST /accounts

Create a new account for a client.

Request Body:
{
  "client_id": "123",
  "account_type": "Savings",
  "currency": "GHS",
  "initial_deposit": 500,
  "status": "Active"
}
View Example Response 
{
  "status": "success",
  "data": {
    "account_id": "acc123",
    "client_id": "123",
    "account_number": "SAV-1234567890",
    "account_type": "Savings",
    "currency": "GHS",
    "balance": 1000,
    "status": "Active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

Transaction Management

GET /transactions

Retrieve a list of transactions.

Query Parameters:
  • account_id (optional) - Filter by account ID
  • transaction_type (optional) - Filter by transaction type ("Deposit", "Withdrawal", "Transfer", "Loan Payment")
  • status (optional) - Filter by status ("Pending", "Completed", "Failed")
View Example Response 
{
  "status": "success",
  "data": [
    {
      "transaction_id": "tx123",
      "account_id": "acc123",
      "transaction_type": "Deposit",
      "amount": 500,
      "currency": "GHS",
      "description": "Initial deposit",
      "reference": "DEP-1612345678",
      "status": "Completed",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

POST /transactions

Create a new transaction (deposit or withdrawal).

Request Body:
{
  "account_id": "acc123",
  "transaction_type": "Deposit",
  "amount": 200,
  "currency": "GHS",
  "description": "Cash deposit",
  "reference": "DEP-1612345679"
}

Note: Supports both Deposit and Withdrawal transaction types. All transaction operations follow double-entry accounting principles.

View Example Response 
{
  "transaction_id": "tx123",
  "account_id": "acc123",
  "transaction_type": "Deposit",
  "amount": 500,
  "currency": "GHS",
  "description": "Initial deposit",
  "reference": "DEP-1612345678",
  "status": "Completed",
  "created_at": "2023-01-01T00:00:00Z"
}

Transfer Management

POST /transfers

Transfer funds between accounts.

Request Body:
{
  "from_account_id": "acc123",
  "to_account_id": "acc456",
  "amount": 100,
  "currency": "GHS",
  "description": "Monthly transfer"
}
View Example Response 
{
  "status": "success",
  "data": {
    "transfer_id": "trf123",
    "from_account_id": "acc123",
    "to_account_id": "acc456",
    "amount": 100,
    "currency": "GHS",
    "description": "Monthly transfer",
    "status": "Completed",
    "created_at": "2023-01-03T00:00:00Z"
  }
}

Error Handling

Common Error Responses

The API uses standard HTTP status codes to indicate the success or failure of requests.

Status Code Description
400 Bad Request - The request was malformed or contains invalid parameters
401 Unauthorized - Authentication is required or the provided credentials are invalid
403 Forbidden - The authenticated user does not have permission to access the requested resource
404 Not Found - The requested resource was not found
500 Internal Server Error - An unexpected error occurred on the server

Example Error Response

{
  "status": "error",
  "message": "Insufficient funds in source account"
}

Common Business Logic Errors

Error Description
Insufficient Funds The account does not have enough balance for the requested withdrawal or transfer
Inactive Account The account is not in an active state (may be inactive or frozen)
Invalid Account Type The operation is not supported for the specified account type
Duplicate Account Number An account with the provided account number already exists

Data Types

Client Types

  • Retail: Individual customers
  • Corporate: Business or organization customers

USSD Status

  • active: USSD banking features are enabled for this client
  • inactive: USSD banking features are disabled for this client

Account Types

  • Savings: Basic savings account
  • Checking: Personal checking account
  • Current: Business current account
  • Loan: Loan account

Account Status

  • Active: Account is active and can perform transactions
  • Inactive: Account is inactive and cannot perform transactions
  • Frozen: Account is frozen, typically due to fraud concerns or legal issues

Transaction Types

  • Deposit: Money added to an account
  • Withdrawal: Money taken from an account
  • Transfer: Money moved between accounts
  • Loan Payment: Payment towards a loan

Transaction Status

  • Pending: Transaction is in progress
  • Completed: Transaction has been successfully processed
  • Failed: Transaction has failed

Double-Entry Accounting System

The API implements full double-entry accounting for all financial transactions. This ensures data integrity and complete audit trails for all money movements within the system.

System Accounts

The system maintains special accounts for handling financial operations:

  • Teller Account - Acts as an intermediary for deposits and withdrawals
  • Vault Account - Represents the bank's main cash reserves

Transaction Flow Example: Deposit

When a deposit is made:

  1. Customer account is credited (balance increases)
  2. Teller account receives funds (credit)
  3. Teller transfers funds to vault (debit teller, credit vault)

Transaction Flow Example: Withdrawal

When a withdrawal is made:

  1. Vault transfers funds to teller (debit vault, credit teller)
  2. Teller gives funds to customer (debit teller)
  3. Customer account is debited (balance decreases)