Request and Response Models

Request and Response Models

This page summarises the most important models across the wrappers and what they are used for.

Connection and Session Models

TerminalNetworkConnection

Defines how the wrapper connects to the terminal.

Field	Purpose
Terminal endpoint	Terminal IP address and port.
UseKeepAlive / useKeepAlive	Controls socket keepalive behaviour.

TerminalEnvironment

Defines the login context for the terminal session.

Field	Purpose
Terminal ID	The primary terminal identifier.
Store ID	Store or merchant-side logical store identifier.
Workstation ID	Identifies the ECR workstation and is required in many EPAS flows.
Secondary terminal IDs	Additional terminal IDs where the solution uses them.
Configuration server	Backend endpoint for configuration.
Authorisation server	Backend endpoint for host or authorisation traffic.
Operator ID	Cashier or operator identity.
Language	ECR or terminal language code.

Transaction Request Models

PurchaseTransactionAmounts

Used for the normal purchase call and for pre-amount completion.

Field	Purpose
Purchase amount	Base purchase amount.
Cashback amount	Cashback requested as part of the transaction.
Merchant category code	MCC when the solution populates it explicitly.

PurchaseRequest

Full purchase request model used when a simple amount is not enough.

Field	Purpose
Amount	Base amount.
Cashback amount	Optional cashback.
Payment method	Alternative payment method such as Swish when supported.
Terminal ID	Optional terminal override for multi-terminal scenarios.
Merchant category code	MCC override where needed.

RefundRequest

Used when refund logic needs more than a plain amount.

Field	Purpose
Amount	Refund amount.
Payment method	Alternative payment method for non-card refund flows.
Reference	Original transaction reference, especially important for alternative methods.
Terminal ID	Optional source terminal override.
Merchant category code	MCC override where needed.

EnableCardReaderOptions

Used with enable or disable reader operations.

Field	Purpose
NotifyOnCancel / notifyOnCancel	Whether a cancellation should surface reader-state notification back to the ECR.
TransactionType / transactionType	Whether the reader is opened for payment, refund, or default behaviour.

Response Models

LoginResponse

Returned by login and indicates whether the terminal session is ready.

Field	Purpose
Logged in flag	Whether login succeeded.
Error condition	Terminal-side failure category when login failed.
Additional information	Free-text explanation from the terminal or wrapper.
Feature versions	Feature-version map where the wrapper exposes it.

LogoutResponse

Returned when the session is explicitly logged out.

Field	Purpose
Logged out flag	Whether logout succeeded.
Error condition	Terminal-side failure category.
Additional information	Diagnostic text when available.

TransactionResponse

The standard result model for purchase, refund, reversal, and cash advance.

Field	Purpose
Approved	Whether the transaction was approved.
Transaction reference	Reference used for reporting, matching, and reversals.
Final amount	Final approved amount including tip, cashback, or add-ons.
Error condition	Failure category when not approved.
Additional information	Human-readable terminal information.

LastTransactionResponse

Returned by last-transaction lookups and recovery workflows.

Area	Typical contents
Result	Approved flag, final amount, error condition, additional info.
Transaction	Type, timestamp, reference, currency, alternative method, base amount, cashback, VAT, tip, and charges.
Merchant	Merchant name, address, city, zip, phone, organisation number.
Card	Merchant PAN, customer PAN, card name, and related card summary data.
Receipts	Merchant and customer receipt text where exposed.

The Swift wrapper currently exposes a partial but useful last-transaction model and can be expanded further toward .NET and Java parity.

EnableReadersResponse

Returned when card readers are opened or closed.

Field	Purpose
Successful	Whether the command succeeded.
Open card readers	Whether the request represented opening rather than closing.
Error condition	Terminal-side failure category.
Additional information	Diagnostic text if present.

AdminResponse

Returned by administrative flows such as host login, print configuration, or parameter update.

Field	Purpose
Successful	Whether the administrative command succeeded.
Error condition	Failure category when it did not.
Additional information	Diagnostic or terminal text.

Receipt Models

ReceiptData

Receipt callbacks deliver structured data rather than a plain text block.

Field	Purpose
Version	Merchant or cardholder copy.
Outcome	Approved, declined, or cancelled transaction outcome.
Reference number	Receipt-side reference number.
Terminal ID	Terminal that produced the receipt.
Operator ID	Operator or cashier context.
Timestamp	Receipt timestamp.
Raw XML	Original print request XML where exposed.
Structured fields	Label, value, and explanation tuples for formatting or UI display.

ReceiptField

Used in the Swift wrapper's receipt presentation model.

Field	Purpose
Label	Field label or heading.
Value	Receipt value.
Explanation	Human-oriented explanation of what the field means.

Callback Support Models

CardAcceptedEventArgs

Used when the terminal notifies the ECR that a payment card has been accepted.

Field	Purpose
Masked card number	PAN masked to a safe display format.
Card number alias	Alias or token-like card identifier where supported.
Card number alias 2	Optional second alias when supplied by the terminal.

Swift callback result wrappers

Type	Purpose
BooleanCallbackResult	Boolean answer plus handled flag.
TextCallbackResult	String answer plus handled flag.
DecimalCallbackResult	Decimal answer plus handled flag.