Transaction Types

This reference covers all transaction types, transfer types, statuses, payment channels, and data models used across the CBA API.

Transaction Types

Type	Description	Endpoint
TRANSFER	Fund transfer between accounts	POST /api/v1/transfers/*
DEPOSIT	Cash or electronic deposit	POST /api/v1/deposits
WITHDRAWAL	Cash or electronic withdrawal	POST /api/v1/withdrawals
PAYMENT	Bill or merchant payment	—
FEE	Service fee charge	Automatic
INTEREST	Interest posting	Automatic
REVERSAL	Reverse a previous transaction	POST /api/v1/transactions/:id/reverse
ADJUSTMENT	Manual balance adjustment	Admin only

Transfer Types

Type	Description	Settlement
INTERNAL	Same-bank transfer	Instant
INTERBANK	Different bank (general)	Minutes
NIP	NIBSS Instant Payment	Seconds to minutes
INTERNATIONAL	Cross-border / SWIFT	1–3 business days

Transaction Statuses

Status	Description	Terminal?
PENDING	Created, awaiting processing	No
PROCESSING	Submitted to provider	No
COMPLETED	Funds delivered	Yes
FAILED	Processing failed	Yes
REVERSED	Reversed after completion	Yes
CANCELLED	Cancelled before processing	Yes

PENDING ──▶ PROCESSING ──▶ COMPLETED
                │                │
                ▼                ▼
             FAILED          REVERSED

PENDING ──▶ CANCELLED

Payment Channels

Channel	Description
MOBILE	Mobile banking app
WEB	Web banking portal
USSD	USSD banking service
ATM	ATM withdrawal/transfer
POS	Point of sale terminal
BRANCH	Branch teller
API	Third-party API integration

Data Models

Transaction Response

{
  "id": "uuid",
  "tenant_id": "uuid",
  "transaction_ref": "TRN20260228001234",
  "transaction_type": "TRANSFER",
  "status": "COMPLETED",
  "source_account_id": "uuid",
  "source_account_num": "1001234567",
  "source_bank_code": "string (for interbank)",
  "dest_account_id": "uuid",
  "dest_account_num": "1001234568",
  "dest_bank_code": "string (for interbank)",
  "dest_account_name": "John Doe",
  "amount": 100000.00,
  "currency": "NGN",
  "fee": 500.00,
  "vat": 50.00,
  "total_amount": 100550.00,
  "transfer_type": "INTERNAL",
  "channel": "API",
  "narration": "Payment for invoice",
  "description": "string (optional)",
  "initiated_by": "uuid",
  "approved_by": "uuid (if approval required)",
  "processed_at": "ISO 8601",
  "completed_at": "ISO 8601",
  "failure_reason": "string (if failed)",
  "external_ref": "string (provider reference)",
  "session_id": "string",
  "reversed_txn_id": "uuid (if reversal)",
  "reversal_reason": "string (if reversal)",
  "metadata": {}
}

Cross-Currency Response (additional fields)

{
  "source_currency": "NGN",
  "target_currency": "USD",
  "exchange_rate": 1580.50,
  "converted_amount": 1000.00,
  "corridor_id": "uuid"
}

Internal Transfer Request

{
  "source_account_id": "uuid (required)",
  "destination_account_id": "uuid (required)",
  "destination_account_name": "string (required)",
  "amount": "number > 0 (required)",
  "currency": "string ISO 4217 (required)",
  "channel": "string (required)",
  "narration": "string max 100 chars (required)",
  "initiated_by": "uuid (required)"
}

Interbank Transfer Request

{
  "source_account_id": "uuid (required)",
  "destination_account_num": "string 10 digits (required)",
  "destination_bank_code": "string CBN code (required)",
  "destination_account_name": "string (required)",
  "amount": "number > 0 (required)",
  "currency": "string ISO 4217 (required)",
  "channel": "string (required)",
  "narration": "string max 100 chars (required)",
  "initiated_by": "uuid (required)"
}

Deposit / Withdrawal Request

{
  "account_id": "uuid (required)",
  "amount": "number > 0 (required)",
  "channel": "string (required)",
  "narration": "string (required)",
  "initiated_by": "uuid (required)"
}

Fee Configuration

{
  "transaction_type": "TRANSFER",
  "transfer_type": "INTERBANK",
  "min_amount": 0.00,
  "max_amount": 999999999.00,
  "fee_type": "FLAT | PERCENTAGE",
  "fee_value": 500.00,
  "min_fee": 100.00,
  "max_fee": 5000.00,
  "vat_rate": 10.0
}

Transaction Limits

{
  "account_type": "SAVINGS",
  "transaction_type": "TRANSFER",
  "transfer_type": "INTERBANK",
  "single_limit": 500000.00,
  "daily_limit": 2000000.00,
  "weekly_limit": 5000000.00,
  "monthly_limit": 10000000.00
}

Journal Model (GL)

{
  "id": "uuid",
  "journal_number": "JNL2602281",
  "journal_type": "string",
  "description": "string",
  "fiscal_period_id": "uuid",
  "transaction_date": "YYYY-MM-DD",
  "effective_date": "YYYY-MM-DD",
  "status": "PENDING | APPROVED | POSTED | REJECTED | REVERSED",
  "source_system": "string",
  "source_reference": "string",
  "source_transaction_id": "uuid (optional)",
  "requires_approval": true,
  "is_reversal": false,
  "is_memo": false,
  "entries": [
    {
      "id": "uuid",
      "line_number": 1,
      "account_id": "uuid",
      "amount": 100000.00,
      "entry_type": "debit | credit",
      "currency_code": "NGN",
      "exchange_rate": 1.0,
      "base_currency_amount": 100000.00,
      "description": "string"
    }
  ]
}

Reference Formats

Field	Format	Example
Transaction ref	TRN{YYYYMMDD}{SEQ}	TRN20260228001234
Journal number	JNL{YYMMDD}{SEQ}	JNL2602281
Account number	10 digits (per-tenant seq)	1001234567
Bank code	CBN institution code	058

Next Steps

• Transactions — Transfer guide with code examples.
• General Ledger — Journal posting and GL accounts.
• Error Codes — Error code reference.