Integration Architecture

Overview

BankLingo integrates with multiple external systems for payment processing, notifications, and regulatory reporting. This document describes the integration patterns, authentication mechanisms, data exchange formats, error handling strategies, and API contracts.

High-Level Integration Architecture

Integration Patterns

1. Payment Integration Pattern

NIBSS Instant Payment Integration

NIBSS Request/Response Models:

Transfer Request:

{
  "sourceAccount": "1234567890",
  "sourceBankCode": "033",
  "destinationAccount": "0987654321",
  "destinationBankCode": "044",
  "amount": 50000.00,
  "narration": "Payment for services",
  "reference": "BLG-TXN-20260101-001",
  "customerName": "John Doe",
  "transactionDate": "2026-01-01T10:30:00Z"
}

Transfer Response (Success):

{
  "status": "SUCCESS",
  "transactionId": "NIBSS-202601-XYZ123",
  "reference": "BLG-TXN-20260101-001",
  "responseCode": "00",
  "responseMessage": "Transaction successful",
  "settlementDate": "2026-01-01T10:30:15Z"
}

Transfer Response (Error):

{
  "status": "FAILED",
  "transactionId": null,
  "reference": "BLG-TXN-20260101-001",
  "responseCode": "25",
  "responseMessage": "Insufficient funds in source account",
  "timestamp": "2026-01-01T10:30:10Z"
}

2. Notification Integration Pattern

Multi-Channel Notification Flow

Notification Service Configurations:

Service	Provider	Authentication	Rate Limit	Retry Strategy
SMS	Termii/Twilio	API Key	100 req/sec	3 retries, exponential backoff
Email	SendGrid	API Key	600 req/min	No retry (accepted = sent)
Push	Firebase Cloud Messaging	Service Account	10,000 req/min	2 retries, linear backoff

SMS Request:

{
  "to": "+2348012345678",
  "from": "BankLingo",
  "sms": "Your transaction of NGN 5,000.00 was successful. Ref: BLG-001. Balance: NGN 50,000.00",
  "type": "plain",
  "channel": "generic",
  "api_key": "TL*********************"
}

Email Request:

{
  "personalizations": [
    {
      "to": [{"email": "user@example.com", "name": "John Doe"}],
      "dynamic_template_data": {
        "transactionAmount": "5,000.00",
        "transactionReference": "BLG-001",
        "accountBalance": "50,000.00"
      }
    }
  ],
  "from": {"email": "noreply@banklingo.com", "name": "BankLingo"},
  "template_id": "d-1234567890abcdef",
  "mail_settings": {
    "sandbox_mode": {"enable": false}
  }
}

Push Notification Request:

{
  "to": "device_token_here",
  "notification": {
    "title": "Transaction Successful",
    "body": "Your transaction of NGN 5,000.00 was successful"
  },
  "data": {
    "transactionId": "txn-123",
    "amount": "5000.00",
    "type": "deposit",
    "click_action": "OPEN_TRANSACTION_DETAILS"
  },
  "priority": "high"
}

3. Webhook Integration Pattern

Inbound Webhook Processing

Webhook Security:

HMAC Signature Verification:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Timestamp Validation:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Webhook Payload Examples:

NIBSS Payment Callback:

{
  "eventType": "payment.completed",
  "transactionId": "NIBSS-202601-XYZ123",
  "reference": "BLG-TXN-20260101-001",
  "status": "SUCCESS",
  "amount": 50000.00,
  "sourceAccount": "1234567890",
  "destinationAccount": "0987654321",
  "settlementDate": "2026-01-01T10:35:00Z",
  "responseCode": "00",
  "responseMessage": "Transaction successful"
}

4. Identity Verification Integration

BVN Verification Flow

BVN Verification Request:

{
  "bvn": "12345678901",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "phoneNumber": "08012345678"
}

BVN Verification Response (Success):

{
  "verified": true,
  "bvn": "12345678901",
  "firstName": "JOHN",
  "lastName": "DOE",
  "middleName": "MICHAEL",
  "dateOfBirth": "1990-05-15",
  "phoneNumber": "08012345678",
  "gender": "Male",
  "nationality": "Nigerian",
  "stateOfOrigin": "Lagos",
  "lgaOfOrigin": "Ikeja",
  "imageBase64": "data:image/jpeg;base64,/9j/4AAQ...",
  "registrationDate": "2015-03-10"
}

API Authentication & Authorization

Authentication Mechanisms

JWT Token Flow

JWT Token Structure:

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (Claims):

{
  "sub": "user-123",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "roles": ["Teller", "Approver"],
  "permissions": [
    "transactions.create",
    "transactions.approve",
    "accounts.read"
  ],
  "branchId": "branch-456",
  "iat": 1735729800,
  "exp": 1735733400,
  "jti": "token-id-789"
}

Access Control Matrix:

Role	Permissions	Transaction Limits
Teller	transactions.create, accounts.read, customers.read	Create: â‚¦500K, Approve: None
Approver	transactions.approve, transactions.read	Create: None, Approve: â‚¦5M
Branch Manager	transactions., accounts., customers.*, reports.read	Create: â‚¦5M, Approve: â‚¦50M
Admin	. (all permissions)	No limits
Auditor	*.read (read-only all)	No transaction operations

Error Handling & Retry Strategies

Retry Policy Matrix

Integration	Error Type	Retry Strategy	Max Retries	Backoff
NIBSS Payment	Timeout	Exponential	3	10s, 30s, 90s
NIBSS Payment	5xx Server Error	Exponential	3	10s, 30s, 90s
NIBSS Payment	4xx Client Error	None	0	N/A
SMS Gateway	Timeout	Exponential	3	5s, 15s, 45s
SMS Gateway	5xx Server Error	Exponential	3	5s, 15s, 45s
SMS Gateway	Rate Limit (429)	Linear	5	60s
Email Service	5xx Server Error	Linear	2	30s, 60s
BVN Verification	Timeout	Exponential	2	20s, 60s
BVN Verification	5xx Server Error	Exponential	2	20s, 60s
Webhook Callback	Processing Error	Exponential	5	10s, 30s, 90s, 270s, 810s

Circuit Breaker Pattern

Circuit Breaker Configuration:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Data Exchange Formats

Standard Request/Response Format

Standard API Response:

{
  "success": true,
  "data": {
    "transactionId": "txn-123",
    "status": "SETTLED",
    "amount": 5000.00
  },
  "message": "Transaction successful",
  "timestamp": "2026-01-01T10:30:00Z",
  "requestId": "req-456"
}

Standard Error Response:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Account has insufficient funds for this transaction",
    "details": {
      "accountBalance": 2000.00,
      "requestedAmount": 5000.00,
      "shortfall": 3000.00
    }
  },
  "timestamp": "2026-01-01T10:30:00Z",
  "requestId": "req-456"
}

Integration-Specific Formats

NIBSS ISO 8583 Format (For card transactions):

                        // Message Type
3838000000C00016             // Bitmap
1234567890123456          // PAN
000000                    // Processing Code
000000005000              // Amount
0101103000                // Transmission Date/Time
123456                    // STAN
123456789012              // Retrieval Reference Number
12345678                  // Card Acceptor Terminal ID
123456789012345           // Card Acceptor ID

NEFT/RTGS XML Format:

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>BLG-20260101-001</MsgId>
      <CreDtTm>2026-01-01T10:30:00</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <TtlIntrBkSttlmAmt Ccy="NGN">50000.00</TtlIntrBkSttlmAmt>
    </GrpHdr>
    <CdtTrfTxInf>
      <PmtId>
        <InstrId>BLG-20260101-001</InstrId>
        <EndToEndId>E2E-123456</EndToEndId>
      </PmtId>
      <IntrBkSttlmAmt Ccy="NGN">50000.00</IntrBkSttlmAmt>
      <Dbtr>
        <Nm>John Doe</Nm>
        <Id>
          <OrgId>
            <Othr>
              <Id>1234567890</Id>
            </Othr>
          </OrgId>
        </Id>
      </Dbtr>
      <CdtrAcct>
        <Id>
          <Othr>
            <Id>0987654321</Id>
          </Othr>
        </Id>
      </CdtrAcct>
    </CdtTrfTxInf>
  </FIToFICstmrCdtTrf>
</Document>

Integration Monitoring & Observability

Key Metrics Tracked

Metric	Purpose	Alert Threshold
API Success Rate	Integration health	< 95%
API Response Time	Performance	P95 > 5s
Token Refresh Rate	Auth health	> 100/min
Retry Count	Reliability	> 50/hour
Circuit Breaker Opens	Service availability	> 5/hour
Webhook Processing Time	Async processing	P95 > 10s
Failed Notifications	Delivery success	> 10%
External API Errors	Third-party health	> 100/hour

Integration Dashboard

Application Insights Queries:

1. External API Success Rate:

dependencies
| where timestamp > ago(1h)
| where type == "HTTP"
| summarize 
    Total = count(),
    Success = countif(success == true),
    Failed = countif(success == false),
    SuccessRate = 100.0 * countif(success == true) / count()
  by target
| order by SuccessRate asc

2. Integration Response Times:

dependencies
| where timestamp > ago(1h)
| where type == "HTTP"
| summarize 
    P50 = percentile(duration, 50),
    P95 = percentile(duration, 95),
    P99 = percentile(duration, 99)
  by target
| order by P95 desc

3. Retry Analysis:

traces
| where timestamp > ago(1h)
| where message contains "Retry attempt"
| parse message with * "Integration: " integration:string " | Attempt: " attempt:int " | " *
| summarize 
    TotalRetries = count(),
    MaxAttempt = max(attempt)
  by integration
| order by TotalRetries desc

Integration Security Best Practices

1. API Key Management

âœ… Store API keys in Azure Key Vault
âœ… Rotate keys quarterly
âœ… Use different keys per environment (dev/staging/prod)
âœ… Implement key versioning for zero-downtime rotation
âœ… Audit all key access in logs

2. TLS/SSL Configuration

âœ… Enforce TLS 1.2+ for all external connections
âœ… Validate SSL certificates (no self-signed in production)
âœ… Use certificate pinning for critical integrations (NIBSS, CBN)
âœ… Implement mutual TLS (mTLS) for high-security integrations

3. Request Signing

âœ… Sign all outbound requests with HMAC-SHA256
âœ… Include timestamp in signature to prevent replay attacks
âœ… Validate inbound webhook signatures
âœ… Use nonce/request ID for idempotency

4. Rate Limiting

âœ… Implement rate limiting on inbound webhooks (100 req/min per IP)
âœ… Respect rate limits of external APIs
âœ… Use exponential backoff when rate-limited (429 responses)
âœ… Cache responses to reduce API calls

5. Data Sanitization

âœ… Sanitize all input data before external API calls
âœ… Validate response data schema before processing
âœ… Mask sensitive data (PAN, BVN) in logs
âœ… Encrypt sensitive data in transit and at rest

Integration Testing Strategy

1. Mock External Services

Stub NIBSS Service (for testing):

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

2. Integration Test Scenarios

Scenario	Test Case	Expected Result
Happy Path	Successful payment	200 OK, transaction settled
Insufficient Funds	Payment exceeds balance	400 Bad Request, specific error
Timeout	External service delay > 30s	504 Gateway Timeout, retry queued
Invalid Token	Expired/invalid auth token	401 Unauthorized, token refresh
Rate Limit	429 response from external API	Retry with backoff
Circuit Breaker	5 consecutive failures	Circuit open, fail fast
Idempotency	Duplicate request ID	Return cached response
Webhook Validation	Invalid signature	401 Unauthorized, log security event

System Architecture - Overall system overview
Component Architecture - Modules and components
Deployment Architecture - Azure infrastructure
Data Flow Architecture - Transaction flows
Security Architecture - Security layers

Summary

The integration architecture provides:

âœ… Payment Integration - NIBSS, NEFT, RTGS with retry logic
âœ… Multi-Channel Notifications - SMS, Email, Push with template management
âœ… Webhook Processing - Secure inbound webhook handling with signature validation
âœ… Identity Verification - BVN verification with caching
âœ… Authentication - JWT-based auth with role-based access control
âœ… Error Handling - Comprehensive retry strategies and circuit breakers
âœ… Data Formats - JSON, XML, ISO 8583 support
âœ… Monitoring - Integration health metrics and alerting
âœ… Security - API key management, TLS, request signing
âœ… Testing - Mock services and comprehensive test scenarios

Integration Characteristics:

Reliability: 99.9% success rate with automatic retries
Performance: P95 < 3s for payment processing
Security: Multi-layered authentication and encryption
Scalability: 500+ TPS for external API calls
Observability: Real-time monitoring and alerting

Overview​

High-Level Integration Architecture​

Integration Patterns​

1. Payment Integration Pattern​

NIBSS Instant Payment Integration​

2. Notification Integration Pattern​

Multi-Channel Notification Flow​

3. Webhook Integration Pattern​

Inbound Webhook Processing​

4. Identity Verification Integration​

BVN Verification Flow​

API Authentication & Authorization​

Authentication Mechanisms​

JWT Token Flow​

Error Handling & Retry Strategies​

Retry Policy Matrix​

Circuit Breaker Pattern​

Data Exchange Formats​

Standard Request/Response Format​

Integration-Specific Formats​

Integration Monitoring & Observability​

Key Metrics Tracked​

Integration Dashboard​

Integration Security Best Practices​

1. API Key Management​

2. TLS/SSL Configuration​

3. Request Signing​

4. Rate Limiting​

5. Data Sanitization​

Integration Testing Strategy​

1. Mock External Services​

2. Integration Test Scenarios​

Related Diagrams​

Summary​

Overview

High-Level Integration Architecture

Integration Patterns

1. Payment Integration Pattern

NIBSS Instant Payment Integration

2. Notification Integration Pattern

Multi-Channel Notification Flow

3. Webhook Integration Pattern

Inbound Webhook Processing

4. Identity Verification Integration

BVN Verification Flow

API Authentication & Authorization

Authentication Mechanisms

JWT Token Flow

Error Handling & Retry Strategies

Retry Policy Matrix

Circuit Breaker Pattern

Data Exchange Formats

Standard Request/Response Format

Integration-Specific Formats

Integration Monitoring & Observability

Key Metrics Tracked

Integration Dashboard

Integration Security Best Practices

1. API Key Management

2. TLS/SSL Configuration

3. Request Signing

4. Rate Limiting

5. Data Sanitization

Integration Testing Strategy

1. Mock External Services

2. Integration Test Scenarios

Related Diagrams

Summary