Bank Account Blacklist

Overview

These commands manage a list of external bank account numbers that your institution wants to block from sending to or receiving from. This is typically used to prevent transactions with known fraud accounts at other banks.

• Blocking outflow prevents your customers from transferring funds to the blacklisted account.
• Blocking inflow prevents your institution from processing credits from the blacklisted account.

Both directions can be controlled independently on the same entry.

Permissions Required

• Write operations (add, update, remove): Security.ManageBankAccountBlacklist
• Read operations (list, check): Security.ViewBankAccountBlacklist or Security.ManageBankAccountBlacklist

---

AddBankAccountBlacklistCommand

Adds an external account number to the blacklist.

Request

{
  "cmd": "AddBankAccountBlacklistCommand",
  "data": {
    "accountNumber": "0123456789",
    "bankCode": "000013",
    "accountName": "John Doe",
    "reason": "Confirmed fraud account — CBN advisory 2026-08-01",
    "blockInflow": true,
    "blockOutflow": true,
    "notifyAudit": false
  }
}

Request Fields

Field	Type	Required	Default	Description
accountNumber	string	Yes	—	The account number to blacklist
bankCode	string	Yes	—	CBN sort code or institution code of the account's bank
accountName	string	No	""	Account holder name — stored for reference only
reason	string	Yes	—	Reason for blacklisting
blockInflow	bool	No	true	Block credits arriving from this account
blockOutflow	bool	No	true	Block transfers sent to this account
notifyAudit	bool	No	false	When true, any transaction attempt on this account triggers an audit notification — use this to monitor accounts under surveillance without fully blocking them

Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Account '0123456789' (bank 000013) has been blacklisted.",
  "data": {
    "id": 7,
    "accountNumber": "0123456789",
    "bankCode": "000013",
    "accountName": "John Doe",
    "blockInflow": true,
    "blockOutflow": true,
    "reason": "Confirmed fraud account — CBN advisory 2026-08-01",
    "isActive": true,
    "notifyAudit": false
  }
}

note

If the account is already actively blacklisted for the same bank code, the command returns an error with the existing entry's ID.

---

UpdateBankAccountBlacklistCommand

Updates an existing blacklist entry — change direction flags, suspend it without deleting, or update the reason.

Request

{
  "cmd": "UpdateBankAccountBlacklistCommand",
  "data": {
    "id": 7,
    "blockInflow": true,
    "blockOutflow": false,
    "isActive": true,
    "notifyAudit": true,
    "reason": "Updated — only inbound transfers blocked pending further review"
  }
}

Request Fields

Field	Type	Required	Description
id	long	Yes	The blacklist entry ID — returned by AddBankAccountBlacklistCommand or GetBankAccountBlacklistQuery
blockInflow	bool	No	Omit to leave unchanged
blockOutflow	bool	No	Omit to leave unchanged
isActive	bool	No	Set false to suspend the entry without deleting it
notifyAudit	bool	No	Omit to leave unchanged
reason	string	No	Omit to leave unchanged

---

RemoveBankAccountBlacklistCommand

Permanently deletes a blacklist entry. Use UpdateBankAccountBlacklistCommand with isActive: false if you want to suspend it temporarily instead.

Request

{
  "cmd": "RemoveBankAccountBlacklistCommand",
  "data": {
    "id": 7
  }
}

Request Fields

Field	Type	Required	Description
id	long	Yes	The blacklist entry ID to permanently remove

---

GetBankAccountBlacklistQuery

Returns all blacklist entries, ordered by most recently added. Supports optional filters.

Request

{
  "cmd": "GetBankAccountBlacklistQuery",
  "data": {
    "activeOnly": true,
    "accountNumber": "0123456789",
    "bankCode": "000013"
  }
}

Request Fields

Field	Type	Required	Description
activeOnly	bool	No	When true, returns only active (non-suspended) entries
accountNumber	string	No	Filter by a specific account number
bankCode	string	No	Filter by a specific bank code

Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "1 entry found.",
  "data": [
    {
      "id": 7,
      "accountNumber": "0123456789",
      "bankCode": "000013",
      "accountName": "John Doe",
      "reason": "Confirmed fraud account",
      "blacklistedBy": "admin@bank.com",
      "blockInflow": true,
      "blockOutflow": true,
      "isActive": true,
      "notifyAudit": false,
      "createdAt": "2026-08-04T10:30:00Z",
      "updateAt": "2026-08-04T10:30:00Z"
    }
  ]
}

---

CheckBankAccountBlacklistQuery

Checks whether a specific account number is blacklisted for a given direction. Returns statusCode: "01" when blacklisted, "00" when clear.

Request

{
  "cmd": "CheckBankAccountBlacklistQuery",
  "data": {
    "accountNumber": "0123456789",
    "bankCode": "000013",
    "direction": "outflow"
  }
}

Request Fields

Field	Type	Required	Default	Description
accountNumber	string	Yes	—	The account number to check
bankCode	string	No	—	When provided, scopes the check to that specific bank
direction	string	No	"outflow"	"inflow" — check if credits from this account are blocked; "outflow" — check if transfers to this account are blocked

Response

{
  "isSuccessful": true,
  "statusCode": "01",
  "message": "Account '0123456789' is blacklisted for outflow.",
  "data": {
    "accountNumber": "0123456789",
    "bankCode": "000013",
    "direction": "outflow",
    "isBlacklisted": true,
    "entryId": 7
  }
}

statusCode	Meaning
"00"	Account is not blacklisted for the specified direction
"01"	Account is blacklisted for the specified direction

Use in BPMN processes

CheckBankAccountBlacklistQuery is useful as a guard step inside a BPMN process before dispatching a transfer or credit — check first, then branch via a gateway based on isBlacklisted.