Skip to main content

Transfers

The platform supports three transfer types: internal (same-bank), external (Nigerian interbank via NIBSS NIP), and international (SWIFT). All transfers go through fraud detection before processing.

Transfer Flow​

Client                 Banking API              NIBSS / SWIFT
  │                        │                        │
  │  POST /transfers/*     │                        │
  │───────────────────────▶│                        │
  │                        │── fraud check ──▶      │
  │                        │◀── risk score ──       │
  │                        │                        │
  │                        │── validate recipient ─▶│
  │                        │◀── name enquiry ──────│
  │                        │                        │
  │                        │── debit wallet         │
  │                        │── submit transfer ────▶│
  │                        │◀── confirmation ──────│
  │  { reference, status } │                        │
  │◀───────────────────────│                        │

Internal Transfers​

Move money between wallets on the same tenant. Settles instantly with zero fees.

POST /api/v1/transfers/internal
curl -X POST https://api.korastratum.com/api/v1/banking/transfers/internal \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: fmfb" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceWalletId": "a1b2c3d4-...",
    "recipientAccountNumber": "0000654321",
    "amount": 50000.00,
    "narration": "Rent payment"
  }'

External Transfers (NIBSS NIP)​

Send money to any Nigerian bank account via the Nigeria Inter-Bank Settlement System.

Step 1: Validate the Recipient​

Before submitting an external transfer, verify the recipient's account:

POST /api/v1/transfers/validate-recipient
{
  "accountNumber": "0000654321",
  "bankCode": "090575"
}

Response:

{
  "success": true,
  "data": {
    "accountNumber": "0000654321",
    "accountName": "JANE SMITH",
    "bankCode": "090575",
    "bankName": "First Microfinance Bank"
  }
}

Step 2: Submit the Transfer​

POST /api/v1/transfers/external
{
  "sourceWalletId": "a1b2c3d4-...",
  "recipientAccountNumber": "0000654321",
  "recipientBankCode": "090575",
  "recipientName": "JANE SMITH",
  "amount": 100000.00,
  "narration": "Invoice #12345",
  "description": "Payment for consulting",
  "saveBeneficiary": true,
  "beneficiaryNickname": "Jane Work"
}

Response:

{
  "success": true,
  "data": {
    "id": "f8e7d6c5-...",
    "transactionId": "t9a8b7c6-...",
    "reference": "FMFB20260227001234",
    "status": "processing",
    "fromAccountNumber": "0000123456",
    "fromAccountName": "John Doe",
    "toAccountNumber": "0000654321",
    "toAccountName": "JANE SMITH",
    "amount": 100000.00,
    "fees": 100.00,
    "totalAmount": 100100.00,
    "narration": "Invoice #12345",
    "timestamp": "2026-02-27T14:22:00Z",
    "estimatedArrival": "2026-02-27T15:30:00Z"
  }
}

External transfers typically settle within minutes. The estimatedArrival field provides the expected completion time.

International Transfers (SWIFT)​

note

International transfers require the internationalTransfersEnabled feature flag on your tenant. Contact support to enable this for enterprise-tier tenants.

POST /api/v1/transfers/international
{
  "sourceWalletId": "a1b2c3d4-...",
  "recipientName": "Acme Corp",
  "recipientAccountNumber": "GB82WEST12345698765432",
  "recipientBankSwiftCode": "WESTGB2L",
  "recipientBankName": "Westminster Bank",
  "recipientCountry": "GB",
  "amount": 5000.00,
  "sourceCurrency": "NGN",
  "destinationCurrency": "GBP",
  "narration": "Supplier payment"
}

The API automatically converts the amount using the current exchange rate available via:

GET /api/v1/fx-rates?from=NGN&to=GBP

Fraud Detection​

Every transfer is automatically screened. You can also call the fraud check endpoint independently:

POST /api/v1/transfers/fraud-check
{
  "amount": 100000.00,
  "recipientAccountNumber": "0000654321",
  "recipientBankCode": "090575",
  "description": "Payment",
  "location": { "lat": 6.5244, "lng": 3.3792 }
}

Response:

{
  "success": true,
  "data": {
    "riskScore": 35,
    "riskLevel": "low",
    "decision": "approve",
    "confidence": 0.95,
    "flags": [],
    "recommendations": []
  }
}
Risk LevelScore RangeAction
low0–30Auto-approve
medium31–60Proceed with monitoring
high61–80Require additional verification
critical81–100Block and flag for review

Transfer Status​

Poll for transfer status:

GET /api/v1/transfers/status/:id
StatusDescription
pendingCreated, awaiting processing
processingSubmitted to NIBSS/SWIFT
completedFunds delivered
failedTransfer failed (see error field)

Beneficiaries​

Save frequently used recipients:

POST /api/v1/transfers/beneficiaries
{
  "accountNumber": "0000654321",
  "bankCode": "090575",
  "accountName": "JANE SMITH",
  "nickname": "Jane Work"
}
GET /api/v1/transfers/beneficiaries
DELETE /api/v1/transfers/beneficiaries/:id

Provider Failover​

The platform uses a circuit breaker pattern for external transfers:

  • Primary provider: Interswitch (configurable)
  • Fallback provider: NIBSS (configurable)
  • Failover trigger: 5 consecutive failures
  • Timeout: 30 seconds per request
  • Retries: Up to 2 retries per attempt

Next Steps​