Transaction Types

This reference covers every transfer type, transaction status, and the data models used across the API.

Transfer Types

Type	Endpoint	Settlement	Fees
Internal	POST /api/v1/transfers/internal	Instant	Free
External (NIBSS)	POST /api/v1/transfers/external	Minutes	₦100 per transfer
International (SWIFT)	POST /api/v1/transfers/international	1–3 business days	Varies by corridor
Bulk	POST /api/v1/bulk-transfers	Varies	Per-item fees apply
Bill Payment	POST /api/v1/bill-payment/pay	Instant to minutes	₦50–₦100
Airtime	POST /api/v1/mobile-money/airtime	Instant	Free
Data	POST /api/v1/mobile-money/data	Instant	Free

Transaction Statuses

Status	Description	Terminal?
pending	Created, awaiting processing	No
processing	Submitted to provider (NIBSS/Interswitch)	No
completed	Funds delivered successfully	Yes
failed	Processing failed — see error field	Yes
reversed	Transaction was reversed after completion	Yes
cancelled	Cancelled before processing	Yes

pending ──▶ processing ──▶ completed
                │                │
                ▼                ▼
             failed          reversed

pending ──▶ cancelled

Transfer Request Model

Internal Transfer

{
  "sourceWalletId": "uuid",
  "recipientAccountNumber": "string (10 digits)",
  "amount": "number (> 0)",
  "narration": "string (max 100 chars)"
}

External Transfer (NIBSS)

{
  "sourceWalletId": "uuid",
  "recipientAccountNumber": "string (10 digits)",
  "recipientBankCode": "string (6 digits)",
  "recipientName": "string",
  "amount": "number (> 0)",
  "narration": "string (max 100 chars)",
  "description": "string (optional)",
  "saveBeneficiary": "boolean (optional, default false)",
  "beneficiaryNickname": "string (optional)"
}

International Transfer (SWIFT)

{
  "sourceWalletId": "uuid",
  "recipientName": "string",
  "recipientAccountNumber": "string (IBAN)",
  "recipientBankSwiftCode": "string (8 or 11 chars)",
  "recipientBankName": "string",
  "recipientCountry": "string (ISO 3166-1 alpha-2)",
  "amount": "number (> 0)",
  "sourceCurrency": "string (ISO 4217)",
  "destinationCurrency": "string (ISO 4217)",
  "narration": "string (max 100 chars)"
}

Transfer Response Model

{
  "id": "uuid",
  "transactionId": "uuid",
  "reference": "string (e.g. FMFB20260227001234)",
  "status": "pending | processing | completed | failed",
  "fromAccountNumber": "string",
  "fromAccountName": "string",
  "toAccountNumber": "string",
  "toAccountName": "string",
  "amount": "number",
  "fees": "number",
  "totalAmount": "number",
  "narration": "string",
  "timestamp": "ISO 8601",
  "estimatedArrival": "ISO 8601 (external/international only)"
}

Transaction History Model

GET /api/v1/transactions

Each transaction in the history list includes:

{
  "id": "uuid",
  "type": "internal_transfer | external_transfer | international_transfer | bill_payment | airtime | data | loan_disbursement | loan_repayment | savings_deposit | savings_withdrawal",
  "direction": "debit | credit",
  "amount": "number",
  "fees": "number",
  "balance": "number (balance after transaction)",
  "reference": "string",
  "narration": "string",
  "counterparty": {
    "accountNumber": "string",
    "accountName": "string",
    "bankName": "string (for external)"
  },
  "status": "pending | processing | completed | failed",
  "timestamp": "ISO 8601"
}

Bill Payment Model

Request

{
  "billerId": "uuid",
  "customerReference": "string",
  "amount": "number (> 0)",
  "description": "string (optional)"
}

Response

{
  "paymentId": "uuid",
  "reference": "string (e.g. BP20260227001234)",
  "billerReference": "string (provider reference)",
  "status": "completed | pending | failed",
  "amount": "number",
  "fees": "number",
  "totalAmount": "number",
  "customerName": "string",
  "timestamp": "ISO 8601"
}

Loan Models

Application Request

{
  "productType": "quick_cash | personal | salary_advance | mortgage | asset_finance | business",
  "requestedAmount": "number",
  "tenureMonths": "number",
  "loanPurpose": "string",
  "employmentStatus": "employed | self_employed | unemployed",
  "employerName": "string (optional)",
  "monthlyIncome": "number",
  "collateral": "string (optional)"
}

Application Response

{
  "applicationId": "uuid",
  "applicationNumber": "string (e.g. LN20260227001)",
  "status": "submitted | under_review | approved | rejected | disbursed",
  "approvalStatus": "pending | level1_approved | level2_approved",
  "requestedAmount": "number",
  "approvedAmount": "number | null",
  "tenure": "number",
  "interestRate": "number | null",
  "approvalLevel": "loan_officer | senior_loan_officer | branch_manager | regional_manager | credit_committee | board",
  "nextReviewDate": "ISO 8601"
}

Savings Models

Request (Target Savings)

{
  "productType": "flexible | target | locked | group | sayt",
  "targetAmount": "number",
  "targetName": "string",
  "targetDate": "ISO 8601 date",
  "monthlyContribution": "number"
}

Response

{
  "accountId": "uuid",
  "productType": "string",
  "balance": "number",
  "targetAmount": "number (target only)",
  "progressPercentage": "number (target only)",
  "interestRate": "number",
  "status": "active | matured | closed",
  "createdAt": "ISO 8601"
}

Reference Formats

Field	Format	Example
Transfer reference	{TENANT}{DATE}{SEQ}	FMFB20260227001234
Bill payment reference	BP{DATE}{SEQ}	BP20260227001234
Loan application number	LN{DATE}{SEQ}	LN20260227001
Account number	10 digits	0000123456
Bank code	6 digits (CBN)	090575
SWIFT code	8 or 11 chars	WESTGB2L

Next Steps

• Transfers — Transfer guide with code examples.
• Error Codes — Error code reference.
• Rate Limits — Request quotas.