BPMCore Terminal Management API

The Terminal Management API provides complete lifecycle management for self-service banking terminals (ATMs, POS devices, kiosks). This API handles terminal creation, configuration updates, status management, and service enabling/disabling.

Base Endpoint

POST /api/core/cmd

Terminal Status Flow

Terminals follow this lifecycle:

• Created → Enabled (activated for use)
• Enabled → Disabled (temporarily deactivated)
• Disabled → Enabled (reactivated)
• Enabled/Disabled → Terminated (permanently unlinked)

Status Types

Status	Description	Can Transact?
ENABLED	Active and operational	Yes
DISABLED	Temporarily inactive	No
TERMINATED	Permanently unlinked	No

Commands & Queries

1. Create Terminal

Registers a new self-service terminal in the system.

Command Name: CreateTerminalCommand

Request Parameters

Parameter	Type	Required	Description
terminalCode	string	Yes	Unique terminal identifier
serialNumber	string	Yes	Device serial number
ptspProviderCode	string	Yes	Payment Terminal Service Provider code
merchantUserId	long	Yes	Merchant/agent user ID
settlementAccountId	long	Yes	Settlement GL account ID
virtualAccountId	long	No	Linked virtual account
terminalName	string	No	Display name for terminal
location	string	No	Physical location

Request Example

{
  "Cmd": "CreateTerminalCommand",
  "Data": {
    "terminalCode": "TRM-001-2024",
    "serialNumber": "SN123456789",
    "ptspProviderCode": "INTERSWITCH",
    "merchantUserId": 12345,
    "settlementAccountId": 5001,
    "terminalName": "Main Branch ATM",
    "location": "Head Office Lobby"
  }
}

Response

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Terminal created successfully.",
  "Data": {
    "TerminalId": 789,
    "TerminalCode": "TRM-001-2024",
    "Status": "ENABLED",
    "CreatedAt": "2024-01-20T10:30:00"
  }
}

2. Update Terminal

Updates terminal configuration details.

Command Name: UpdateTerminalCommand

Request Parameters

Parameter	Type	Required	Description
terminalId	long	Yes	Terminal ID to update
terminalCode	string	No	New terminal code
serialNumber	string	No	New serial number
ptspProviderCode	string	No	New PTSP provider
terminalName	string	No	New display name
location	string	No	New location

Request Example

{
  "Cmd": "UpdateTerminalCommand",
  "Data": {
    "terminalId": 789,
    "terminalName": "Branch ATM - Updated",
    "location": "Relocated to Entrance"
  }
}

3. Enable Terminal

Activates a terminal for transaction processing.

Command Name: EnableTerminalCommand

Request Parameters

Parameter	Type	Required	Description
terminalId	long	Yes	Terminal ID to enable

Request Example

{
  "Cmd": "EnableTerminalCommand",
  "Data": {
    "terminalId": 789
  }
}

Response

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Terminal enabled successfully.",
  "Data": {
    "TerminalId": 789,
    "Status": "ENABLED",
    "EnabledAt": "2024-01-20T14:00:00"
  }
}

4. Disable Terminal

Deactivates a terminal temporarily (can be re-enabled).

Command Name: DisableTerminalCommand

Request Parameters

Parameter	Type	Required	Description
terminalId	long	Yes	Terminal ID to disable
reason	string	No	Reason for disabling

Request Example

{
  "Cmd": "DisableTerminalCommand",
  "Data": {
    "terminalId": 789,
    "reason": "Maintenance required"
  }
}

5. Terminate Terminal

Permanently terminates/unlinks a terminal from a merchant. Terminated terminals can be reassigned to new merchants.

Command Name: TerminateTerminalCommand

Request Parameters

Parameter	Type	Required	Description
terminalId	long	Yes	Terminal ID to terminate
reason	string	No	Termination reason

Request Example

{
  "Cmd": "TerminateTerminalCommand",
  "Data": {
    "terminalId": 789,
    "reason": "Merchant contract ended"
  }
}

Response

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Terminal terminated successfully.",
  "Data": {
    "TerminalId": 789,
    "Status": "TERMINATED",
    "TerminatedAt": "2024-01-20T16:00:00"
  }
}

6. Retrieve Terminals List

Retrieves a paginated list of terminals with filtering options.

Command Name: RetrieveTerminalsListQuery

Request Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: "ENABLED", "DISABLED", "TERMINATED"
merchantUserId	long	No	Filter by merchant user
ptspProviderCode	string	No	Filter by PTSP provider
searchText	string	No	Search in terminal code, serial number
pageNumber	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20)
isExport	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveTerminalsListQuery",
  "Data": {
    "status": "ENABLED",
    "merchantUserId": 12345,
    "pageNumber": 1,
    "pageSize": 50
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Terminals retrieved successfully.",
  "Data": {
    "items": [
      {
        "Id": 789,
        "TerminalCode": "TRM-001-2024",
        "SerialNumber": "SN123456789",
        "TerminalName": "Main Branch ATM",
        "Location": "Head Office Lobby",
        "Status": "ENABLED",
        "PtspProviderCode": "INTERSWITCH",
        "MerchantUserId": 12345,
        "MerchantName": "ABC Enterprises",
        "SettlementAccountId": 5001,
        "SettlementAccountNumber": "1001234567",
        "VirtualAccountId": 8001,
        "EnableMerchantServices": true,
        "EnableAgentServices": false,
        "CreatedAt": "2024-01-15T10:00:00",
        "LastUpdated": "2024-01-20T14:00:00"
      }
    ],
    "totalRows": 45,
    "totalPages": 1,
    "pageSize": 50,
    "currentPage": 1
  }
}

7. Retrieve Terminal By ID

Retrieves detailed information for a single terminal.

Command Name: RetrieveTerminalByIdQuery

Request Parameters

Parameter	Type	Required	Description
terminalId	long	Yes	Terminal ID

Request Example

{
  "Cmd": "RetrieveTerminalByIdQuery",
  "Data": {
    "terminalId": 789
  }
}

8. Get Provider Terminal By Serial

Looks up a terminal by serial number and provider.

Command Name: GetProviderTerminalBySerialQuery

Request Parameters

Parameter	Type	Required	Description
serialNumber	string	Yes	Device serial number
ptspProviderCode	string	Yes	PTSP provider code

Request Example

{
  "Cmd": "GetProviderTerminalBySerialQuery",
  "Data": {
    "serialNumber": "SN123456789",
    "ptspProviderCode": "INTERSWITCH"
  }
}

9. Look Up Terminals

Quick lookup for terminal autocomplete/selection.

Command Name: LookUpTerminalsQuery

Request Parameters

Parameter	Type	Required	Description
searchText	string	No	Search term
status	string	No	Filter by status
merchantUserId	long	No	Filter by merchant
pageSize	integer	No	Max results (default: 10)

Request Example

{
  "Cmd": "LookUpTerminalsQuery",
  "Data": {
    "searchText": "TRM-001",
    "status": "ENABLED",
    "pageSize": 10
  }
}

10. Enable Merchant Services

Enables merchant services for a terminal user.

Command Name: EnableMerchantServicesCommand

Request Parameters

Parameter	Type	Required	Description
userId	long	Yes	Self-service user ID

11. Disable Merchant Services

Disables merchant services for a terminal user.

Command Name: DisableMerchantServicesCommand

Request Parameters

Parameter	Type	Required	Description
userId	long	Yes	Self-service user ID

12. Enable Agent Services

Enables agent banking services for a terminal user.

Command Name: EnableAgentServicesCommand

13. Disable Agent Services

Disables agent banking services for a terminal user.

Command Name: DisableAgentServicesCommand

---

Business Rules

Terminal Creation

1. Unique Terminal Code: No duplicate terminal codes allowed
2. Unique Serial Number: Serial number must be unique per PTSP provider
3. Valid Merchant: Merchant user must exist and be active
4. Settlement Account: Must be a valid GL account
5. PTSP Provider: Must be a configured provider in the system

Terminal Updates

1. Status Check: Cannot update terminated terminals
2. Active Transactions: System may prevent updates during active transactions
3. Cache Invalidation: Central cache is cleared on updates

Terminal Termination

1. Irreversible: Termination is permanent (cannot be undone)
2. Reassignment: Terminated terminals can be reassigned to new merchants
3. Transaction Restriction: No new transactions allowed after termination
4. Audit Trail: Full termination history maintained

---

Common Use Cases

Example 1: Terminal Onboarding

// Step 1: Create terminal
{
  "Cmd": "CreateTerminalCommand",
  "Data": {
    "terminalCode": "TRM-BRANCH-01",
    "serialNumber": "ATM987654321",
    "ptspProviderCode": "NIBSS",
    "merchantUserId": 12345,
    "settlementAccountId": 5001,
    "terminalName": "Lagos Branch ATM",
    "location": "1st Floor, Main Entrance"
  }
}

// Step 2: Enable merchant services
{
  "Cmd": "EnableMerchantServicesCommand",
  "Data": {
    "userId": 12345
  }
}

Example 2: Terminal Maintenance

// Disable for maintenance
{
  "Cmd": "DisableTerminalCommand",
  "Data": {
    "terminalId": 789,
    "reason": "Scheduled maintenance - Software update"
  }
}

// ... perform maintenance ...

// Re-enable after maintenance
{
  "Cmd": "EnableTerminalCommand",
  "Data": {
    "terminalId": 789
  }
}

Example 3: Merchant Change

// Terminate from old merchant
{
  "Cmd": "TerminateTerminalCommand",
  "Data": {
    "terminalId": 789,
    "reason": "Merchant contract ended - Reassigning to new location"
  }
}

// Create new assignment
{
  "Cmd": "CreateTerminalCommand",
  "Data": {
    "terminalCode": "TRM-NEWLOC-01",
    "serialNumber": "ATM987654321",
    "ptspProviderCode": "NIBSS",
    "merchantUserId": 67890,
    "settlementAccountId": 5002
  }
}

---

Integration Notes

PTSP Providers

Common Payment Terminal Service Providers:

• INTERSWITCH
• NIBSS
• UPSL
• PAYSTACK
• Custom provider codes

Settlement Flow

1. Terminal transactions are settled to the configured settlementAccountId
2. Virtual accounts can be linked for multi-currency settlement
3. Real-time settlement tracking via journal entries
4. Reconciliation reports available

Cache Management

The system uses central caching for terminal data:

• Cache is automatically cleared on terminal updates
• Terminal lookups are cached for performance
• Cache key pattern: terminal:{terminalId}
• TTL: Configurable (default: 1 hour)

---

Best Practices

1. Consistent Naming: Use standardized terminal code patterns (e.g., TRM-<BRANCH>-<NUMBER>)
2. Location Details: Include precise location information for field support
3. Status Management: Always provide reasons when disabling/terminating
4. Regular Audits: Periodically review terminal status and usage
5. Merchant Validation: Verify merchant active status before terminal creation
6. Serial Number Tracking: Maintain accurate serial number records for warranty/support

---

Related APIs:

• Virtual Accounts
• General Ledger Accounts
• Merchant Management

---

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer