Social Banking API Documentation

Introduction

This API documentation provides information about the endpoints available for integrating with our social banking platform. The API supports both WhatsApp and USSD channels for various banking operations.

Authentication

Card Registration

Register a new user with card details:

{
    "endpoint": "POST /api/auth/register/card",
    "body": {
        "card_number": "1234567890123456",
        "expiry": "12/25",
        "cvv": "123",
        "phone_number": "260971234567"
    }
}

Account Registration

Register a new user with account details:

{
    "endpoint": "POST /api/auth/register/account",
    "body": {
        "account_number": "1234567890",
        "id_number": "123456/78/9",
        "phone_number": "260971234567"
    }
}

Money Transfer

Internal Transfer

Transfer money to another account:

{
    "endpoint": "POST /api/transfer/internal",
    "body": {
        "sender": "1234567890",
        "recipient": "0987654321",
        "amount": 1000.00,
        "pin": "1234"
    }
}

Bank Transfer

Transfer money to another bank:

{
    "endpoint": "POST /api/transfer/bank",
    "body": {
        "sender": "1234567890",
        "bank_name": "Example Bank",
        "bank_account": "0987654321",
        "amount": 1000.00,
        "pin": "1234"
    }
}

Mobile Money Transfer

Transfer money to mobile money:

{
    "endpoint": "POST /api/transfer/mobile",
    "body": {
        "sender": "1234567890",
        "recipient": "260971234567",
        "amount": 1000.00,
        "pin": "1234"
    }
}

Bill Payments

Validate Bill Account

Validate a bill account number:

{
    "endpoint": "POST /api/bills/validate",
    "body": {
        "account_number": "1234567890",
        "bill_type": "ELECTRICITY"
    }
}

Pay Bill

Make a bill payment:

{
    "endpoint": "POST /api/bills/pay",
    "body": {
        "payer": "1234567890",
        "bill_account": "0987654321",
        "bill_type": "ELECTRICITY",
        "amount": 1000.00,
        "pin": "1234"
    }
}

Account Services

Balance Inquiry

Check account balance:

{
    "endpoint": "POST /api/account/balance",
    "body": {
        "account_number": "1234567890",
        "pin": "1234"
    }
}

Mini Statement

Get mini statement:

{
    "endpoint": "POST /api/account/mini-statement",
    "body": {
        "account_number": "1234567890",
        "pin": "1234"
    }
}

Full Statement

Get full statement:

{
    "endpoint": "POST /api/account/statement",
    "body": {
        "account_number": "1234567890",
        "pin": "1234",
        "start_date": "2024-01-01",
        "end_date": "2024-03-21",
        "per_page": 20
    }
}

Channel-Specific Endpoints

WhatsApp Webhook

WhatsApp webhook endpoint:

{
    "endpoint": "POST /whatsapp/webhook",
    "description": "Handles incoming WhatsApp messages"
}

USSD Handler

USSD request handler:

{
    "endpoint": "POST /ussd/handle",
    "body": {
        "sessionId": "session123",
        "phoneNumber": "260971234567",
        "text": "1",
        "serviceCode": "*123#"
    }
}

Error Handling

All endpoints return errors in the following format:

{
    "status": "error",
    "message": "Detailed error message",
    "code": "ERROR_CODE"  // Optional error code
}