​
Overview

Terminal action allows developers to insert custom decision making logic to extend Nomba Terminal features behaviour during different transaction scenarios. Imagine your terminal is about to: • Check balance • Make a payout • Perform another financial action Instead of instantly completing the action, Terminal action pulse the process, send the transaction data to your backend system and wait for your system’s approval to either reject or continue the process. After your system’s instruction(based on your business rule) it sends a response back to the terminal to: • Proceed with the transaction • Modify some parameters • Cancel or reject the action Think of it as middleware for your terminal — it gives your infrastructure control over what happens next in real time.

​
Quick Action

Pre-Balance Check

Intercept balance check requests to apply validation or custom logic.

Payout Transactions

Customize or approve payout transactions before they are processed.

​
Terminal Actions Scenarios

Terminal actions can be triggered at different stages of a transaction to allow custom business logic to run before proceeding. Below are examples of supported scenarios, their action precedence, types, and execution modes.
ScenarioAction TypeMode
Payoutpre-payout-authSynchronous
Balance Checkpre-balance-check-authSynchronous
Synchronous Mode:
In synchronous mode, the terminal will wait for your backend to respond before moving forward with the transaction.

​
Precedence

Precedence defines the exact point in the transaction pipeline where a terminal action is triggered.
It determines when your custom logic is executed relative to the terminal’s built-in process — such as before showing a balance or after requesting a PIN. This lets you: • Enforce business rules before the terminal proceeds • Reject unauthorized actions early • Run validations like balance checks and similar actions
  1. pre-payout-auth: Triggered when a user is about to initiate a payout transaction, immediately after the terminal requests a PIN. This allows you to validate the transaction, apply rules, or reject it before processing.

Payout Transaction Flow (pre-payout-auth)

  1. pre-balance-check-auth: Triggered when a user attempts to check their wallet or account balance. This provides an opportunity to authorize or restrict access based on custom logic.

Balance Check Flow (pre-balance-check-auth)

​
Reason Code List

Terminal Action responses include a reasonCode that indicates the outcome of your custom logic and guides the terminal on what to do next. These codes help standardize system responses, making them easy to interpret programmatically.

​
What is a reasonCode?

A reasonCode is a status flag returned in your response to indicate whether the transaction should proceed or not, and why It is paired with shouldActionProceed: true/false to clearly guide the terminal’s next step. 
{
	"shouldActionProceed": true,
	"reasonCode": "00"		 
}

​
Reason Code Reference

CodeMeaningDescription
00SUCCESSThe action passed all checks — proceed with the transaction.
01FAILEDA generic failure occurred — stop the transaction.
02BLACKLISTEDThe terminal or customer is blacklisted and cannot perform this action.
03TERMINAL_NOT_FOUNDThe terminal making the request does not exist in your system.
04ACCOUNT_NOT_FOUNDThe associated account could not be located.
05INVALID_PINThe PIN provided is incorrect or unauthorized.
06LIMIT_EXCEEDEDThe transaction amount exceeds the allowable limit.
07INSUFFICIENT_BALANCEThe account does not have enough funds to complete the transaction.