Skip to main content

​
Account Management Guide

This guide covers everything you need to know about managing bank accounts in your Open Banking application, from opening new accounts to managing account holds and statuses.

​
Overview

Account management is a core component of any Open Banking application. Our API supports comprehensive account operations that allow you to create, manage, and monitor bank accounts for your customers. This functionality enables you to provide a complete banking experience within your application.

​
Key Account Operations

​
1. Open New Accounts

The account creation process allows you to open new bank accounts for your customers. The system will generate a unique account number and set up the account with the specified parameters. When opening a new account, you’ll need to provide customer identification details. Upon opening of account, customers will get an email. Please follow the instruction in the email. Generally customers will be asked to complete Account Opening registration which involves further compliances check, live image capture and verification. It is impportant customers follow the instruction in order for them to be able to access full service. 
curl -X POST ${API_BASE_URL}/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "sex": "M",
    "email": "john@sparklemfb.ng",
    "bvn": "12345678905",
    "phone": "+2349063473324",
    "dob": "1990-01-01",
    "proof_of_id": {
      "document_type": "passport",
      "document": "A12345678"
    },
    "proof_of_address": {
      "document_type": "utility_bill",
      "document": "Utility Bill Document"
    },
    "address": {
      "street": "123 Main St",
      "area": "Downtown",
      "city": "Metropolis",
      "local_government": "Central",
      "country": "NG"
    },
    "next_of_kin": {
      "first_name": "Jane",
      "surname": "Doe",
      "gender": "F",
      "email": "jane.doe@sparklemfb.ng",
      "phone": "+234987654321",
      "relationship": "sister",
      "address": {
        "street": "456 Side St",
        "area": "Uptown",
        "city": "Metropolis",
        "local_government": "North",
        "country": "NG"
      }
    },
    "custom_properties": [
      {
        "id": "<string>",
        "description": "<string>",
        "type": "<string>",
        "value": "<string>"
      }
    ]
  }'

{
    "status": "success",
    "message": "Operation successful",
    "data": {
        "customer_id": "8cbd589f-a15d-4214-bc08-69160b237a6e",
        "account_type": "personal",
        "status": "ACTIVE",
        "custom_properties": [
          {
            "id": "<string>",
            "description": "<string>",
            "type": "<string>",
            "value": "<string>"
          }
        ]
    }
}
Opening new account does not require customer consent so therefore there is no need to request for scope to carry out this API call. Use client credentials authentication method.

​
2. Retrieve Account Information

This operation enables you to retrieve all accounts belonging to a specific customer. You can view account details including account numbers, account types, balances, and current status. This is useful for displaying a customer’s complete banking portfolio in your application. The system returns comprehensive account information including account names, types, currencies, and current operational status. This data helps you provide customers with a complete view of their banking relationships. 
curl -X GET ${API_BASE_URL}/accounts \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": [
      {
          "customer_id": "c3641f2e-3082-4ca6-96e2-086ef82c10c4",
          "account_name": "Hello Dev",
          "account_number": "1000000350",
          "product_id": "Personal",
          "currency_code": "NGN",
          "account_opening_date": "2025-05-15",
          "account_type": "Current",
          "bvn": "234802325829",
          "phone": "2348023258292",
          "email": "hellodevelo+1@gmail.com",
          "custom_properties": []
      },
      {
          "customer_id": "c3641f2e-3082-4ca6-96e2-086ef82c10c4",
          "account_name": "Reverb",
          "account_number": "1000000367",
          "product_id": "Business",
          "currency_code": "NGN",
          "account_opening_date": "2025-05-20",
          "account_type": "Current",
          "bvn": "234802325829",
          "phone": "2348023258292",
          "email": "hellodevelo+1@gmail.com",
          "custom_properties": []
      }
  ]
}
Make sure you send the scope accounts.list.readonly while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
3. Check Account Balance

Balance checking allows you to retrieve the current available and ledger balances for any account. This operation provides real-time balance information that you can display to customers or use for transaction processing decisions. The balance information includes both available funds (which can be used for transactions) and ledger balance (the total account balance). This distinction is important for accounts that may have pending transactions or holds. 
curl -X GET ${API_BASE_URL}/accounts/${account_number}/balances \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": {
      "account_number": "1000000350",
      "currency": "NGN",
      "available_balance": 9969050,
      "cleared_balance": "N/A",
      "uncleared_balance": "N/A",
      "hold_balance": "N/A",
      "minimum_balance": 0
  }
}
Make sure you send the scope accounts.balance.readonly while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
4. View Transaction History

Transaction history provides detailed records of all account activity. You can retrieve transaction lists with filtering options for date ranges, transaction types, and amounts. This feature enables customers to review their account activity and helps with financial planning and reconciliation. The transaction history includes details such as transaction amounts, descriptions, timestamps, and status information. You can implement pagination to handle large transaction volumes efficiently. 
curl -X GET ${API_BASE_URL}/accounts/${account_number}/transactions \
  -H "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
  -H "idempotency_key: ${IDEMPOTENCY_KEY}" \
  -H "signature: ${SIGNATURE}"

{
  "status": "success",
  "message": "Operation successful",
  "data": [
    {
        "id": 13420,
        "savingsId": 35,
        "resourceId": 872,
        "clientId": 24,
        "transactionTypeValue": "Withdrawal",
        "currencyCode": "NGN",
        "paymentTypeId": "2",
        "paymentTypeName": "NIP OUTGOING",
        "fraud_status": 0,
        "reversed": "0",
        "note": "Transfer to Edomwande Ikponmwosa George",
        "senderNuban": "1000000350",
        "senderName": null,
        "senderBankCode": null,
        "destinationNuban": "0016819451",
        "destinationName": "Edomwande Ikponmwosa George",
        "destinationBankCode": "000013",
        "location": "6.429370,3.435580",
        "amount": "10025.00000000",
        "fee": "0.00",
        "runningBalance": "9970050.00000000",
        "submittedOnTimeStamp": "2025-07-18 21:08:35",
        "categoryId": null,
        "categoryIcon": "https://cloudfilesstore.blob.core.windows.net/categories/Others.png",
        "categoryName": "General",
        "categorization_id": null,
        "receiptUrl": null,
        "created_at": "2025-07-18 16:38:35",
        "updated_at": "2025-07-18 16:38:35",
        "reference": "090325250718160734983124385316",
        "merchantId": null,
        "merchantName": null,
        "senderUuid": "c3641f2e-3082-4ca6-96e2-086ef82c10c4::1000000350::false",
        "destinationUuid": null,
        "merchantLogo": null,
        "deleted_at": null
    },
    {
        "id": 13419,
        "savingsId": 35,
        "resourceId": 864,
        "clientId": 24,
        "transactionTypeValue": "Withdrawal",
        "currencyCode": "NGN",
        "paymentTypeId": "2",
        "paymentTypeName": "NIP OUTGOING",
        "fraud_status": 0,
        "reversed": "0",
        "note": "Transfer to Anthony Corwin",
        "senderNuban": "1000000350",
        "senderName": null,
        "senderBankCode": null,
        "destinationNuban": "0016819451",
        "destinationName": "Anthony Corwin",
        "destinationBankCode": "000013",
        "location": "6.429370,3.435580",
        "amount": "10025.00000000",
        "fee": "0.00",
        "runningBalance": "9980075.00000000",
        "submittedOnTimeStamp": "2025-07-15 23:40:05",
        "categoryId": null,
        "categoryIcon": "https://cloudfilesstore.blob.core.windows.net/categories/Others.png",
        "categoryName": "General",
        "categorization_id": null,
        "receiptUrl": null,
        "created_at": "2025-07-15 19:10:05",
        "updated_at": "2025-07-15 19:10:05",
        "reference": "090325250715190705144721936458",
        "merchantId": null,
        "merchantName": null,
        "senderUuid": "c3641f2e-3082-4ca6-96e2-086ef82c10c4::1000000350::false",
        "destinationUuid": null,
        "merchantLogo": null,
        "deleted_at": null
    }
  ]
}
Make sure you send the scope accounts.transactions.readonly while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
5. Update Account Status

Sparkle will not be supporting this capability.

​
6. Place Account on Hold

Account holds are temporary restrictions that can be placed on accounts to prevent certain types of transactions. You can place different types of holds including debit holds (preventing withdrawals), credit holds (preventing deposits), or full holds (preventing all transactions). Holds are useful for fraud prevention, compliance requirements, or pending investigations. Each hold includes an expiration date and reason for the restriction.
Make sure you send the scope accounts.holds.create while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
7. Release a Hold on Account

Hold release allows you to remove specific restrictions from accounts when the underlying issue has been resolved. You can release individual holds or all holds on an account, restoring normal account functionality. Hold releases should be performed promptly when the reason for the hold has been addressed. The system maintains records of all hold activities for audit purposes.
Make sure you send the scope accounts.holds.update while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
8. View All Holds on Account

This operation provides a complete view of all active holds on an account. You can see hold details including types, amounts, reasons, and expiration dates. This information helps you understand current account restrictions and plan appropriate actions.
Make sure you send the scope accounts.holds.readonly while requesting for a token, failure to send the scope will lead to the issued access token not able to access this API.

​
Account Features

​
Account Statuses

Accounts can have different operational statuses:
  • ACTIVE: Fully operational accounts with all features available
  • INACTIVE: Accounts that are temporarily suspended or dormant. These accounts cannot perform transactions but can be reactivated. Common reasons include inactivity, pending verification, or temporary suspension by the customer or bank.
  • BLOCKED: Accounts that are permanently or temporarily blocked due to security concerns, compliance issues, or fraud detection. These accounts cannot perform any transactions and require manual intervention to unblock.
  • OTHER: Accounts with specialized statuses that don’t fit into the standard active, inactive, or blocked categories. This may include accounts under investigation, accounts with special restrictions, or accounts in transition between statuses.

​
Account Status Codes

When retrieving account information or processing transactions, you may encounter the following status codes:
CodeDescription
00Approved or completed successfully
01Status unknown
03Invalid Sender
05Do not honor
06Dormant Account
07Invalid Account
09Request processing in progress

​
Use Cases and Applications

​
Customer Onboarding

Account management APIs are essential for customer onboarding processes. You can create accounts as part of the customer registration workflow, ensuring new customers have immediate access to banking services.

​
Next Steps

Now that you understand account management operations, explore these related topics:
Always ensure proper consent and authorization before performing account operations. Implement robust error handling and security measures to protect customer data and maintain account integrity. Regular monitoring and compliance with regulatory requirements are essential for successful account management implementation.