Nuvei Payment Terminal

On-Premise Integration

Device Mode: USB – RS232 – WiFi – Ethernet
Host Modes: Direct API Device – App 2 App Inter-Link

API v1.3.34 QA_1.3.34 2026-09-29

REST API specification for integrating a third-party POS system with a payment terminal over a local network. Covers all transaction types, receipt options, async mode, and signature approval flow.

Introduction

Payment gateway integration with a POS system enables customers to make purchases quickly and securely from their POS device to the payment terminal. Integrators are responsible for meeting applicable PCI DSS and PCI Software Security Framework requirements.

The POS Integration API is consumed by a POS or middleware system talking to a payment terminal on a local network. The public contract and examples use JSON. The runtime also accepts legacy XML content types for backward compatibility; XML is outside this public contract.

Technical Requirements

SessionId — non-empty string generated by the POS software; maximum 36 characters. UUID/GUID format is recommended but not enforced by the server; use a unique value for each transaction request.
Base endpoint — the IP address (local network) of the terminal which runs the Payment app.
X-API-KEY — required when the TMS-configured authorization key is set. Missing or wrong key returns an error response. The client may generate the key in any form (maximum 32 characters); the value configured in TMS and the value sent in X-API-KEY must be identical. Sample TMS key: 6B9F2A81D3E47C5A0B1F9E8D7C6B5A43.

Quick Start

Configure the terminal IP address and port on the local network (the base endpoint of the Payment app).
Generate a unique non-empty sessionId (maximum 36 characters) for each transaction request.
(Optional) Add the X-API-KEY header if TMS request authorization is configured.
Construct the request URI and POST or GET to the appropriate endpoint — see API Requests below.

Sync vs Async Mode

Transaction requests support two communication modes. The default is synchronous (AsyncMode disabled). Set AsyncMode enabled to use async mode — the terminal returns an immediate status acknowledgement and the client polls querytransaction for the final result.

Synchronous — default (all endpoints)

The POS sends a request and blocks until the terminal returns the full HTTP response. Single request, single response.

Summary

Default mode for all endpoints — transaction and non-transaction.
AsyncMode defaults to disabled.
POS waits and blocks until the HTTP response arrives.
Single request → single response.

Asynchronous — transaction endpoints only

Transactions in async mode allow the merchant to call the API to start the transaction and receive its status immediately, without waiting for the POS terminal to complete the transaction for a final response. The client retrieves the current status by calling querytransaction.

Summary

Only available for transaction endpoints (POST /transaction with AsyncMode enabled).
Initial response ResponseType is always "querytransaction".
POS must poll GET /querytransaction repeatedly using the same sessionId as the original transaction URL.
When Status = 11 (WaitingForSignatureConfirmationFromClient) with DigitalSig present, call POST /approvesignature (same sessionId) then continue polling — see Table ENUM-12.
When Status = 1 (TransactionCompleted), the Transaction object contains the full result — see Table ENUM-12.

Table ENUM-12 — Status and StatusText field values

Enum table — colocated with Sync vs Async. Used by Query Transaction and async Status on transaction responses. Also in Table Index.

Here are some values for the Status and StatusText fields returned in async mode responses (ResponseType: "querytransaction").

Value of "Status" field	Value of "StatusText" field	Description
None = 0		No active transaction stage.
TransactionCompleted = 1	Transaction completed	The transaction has been completely processed. The `Transaction` object in the response contains the full result when status equals `1`.
Initialize = 2	Initializing transaction	The transaction is being initialized.
AwaitingUserInteraction = 3	Awaiting user interaction	Waiting for the user to complete required actions (signature, select account type ...)
WaitingForCard = 4	Waiting for card	Waiting for the card to be presented.
CardProcessing = 5	Card processing	The card is currently being processed.
TransactionProcessing = 6	Transaction Processing	The transaction is being processed.
TransactionProcessed = 7	Transaction Processed	The transaction has been processed.
WaitingForCardRemove = 8	Waiting For Card Remove	Waiting for the card to be removed.
WaitingForMerchantCard = 9	Waiting For Merchant Card	The transaction requires the user to swipe the merchant card.
WaitingForSignatureConfirmation = 10	Waiting For Signature Confirmation	The payment app is auto-approving the signature without POS app interaction.
WaitingForSignatureConfirmationFromClient = 11	Waiting For Signature Confirmation From Client	Waiting for the POS app to approve or reject the captured signature. Call Approve Signature (`POST /approvesignature`) with the required `Approval` value, then continue polling.
GettingSignatureFromCustomer = 12	Getting Signature From Customer	The system is prompting the customer to provide a signature.
DCCSelecting = 13	DCC Selecting	The system is presenting DCC (Dynamic Currency Conversion) options to the user.
SelectAccountType = 14	Select Account Type	Waiting for the cardholder to select an account type.
EnterPin = 15	Enter PIN	Waiting for the cardholder to enter a PIN.
WaitingForProductData = 16	Waiting For Product Data	Waiting for product/SKU data from the POS.

API Requests

Request URI

The request URI is made up of three parts: the base URL, a sessionId, and the type of request to make.

The base endpoint is the IP address (local network) of the terminal which runs the Payment app.
A sessionId is a non-empty string that identifies the current third-party software request. The maximum is 36 characters; UUID/GUID format is recommended but not enforced by the server.
The request type portion of the path is the endpoint suffix for the function being called (see Request Types below).
An API Request object should be constructed and posted to the appropriate API endpoint.

URL Pattern

https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/{{endpoint}}

Example URIs

URI
https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/transaction
https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/querytransaction
https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/merchantlist
https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/settlement
https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/approvesignature

Request Authorization

This feature is disabled by default, so resellers need to set the key in TMS to restrict client requests. After configuring this authorization value, clients need to add it as a header item to authorize requests (X-API-KEY). The Authorization Key set in TMS allows a maximum of 32 characters.

There is no required generation algorithm. The client may create the key in any format they choose (letters, digits, hex string, etc.), as long as the same value is configured on TMS and sent in the X-API-KEY request header.

Sample Authorization Key used as a TMS template default:

Sample TMS Authorization Key

6B9F2A81D3E47C5A0B1F9E8D7C6B5A43

If the header is missing or contains an incorrect key, the terminal returns an error response.

POS Integration Options screen showing Authorization Key field configured in TMS

POS Integration Options — the Authorization Key is configured on the terminal via TMS (maximum 32 characters). Clients must send the same value in the X-API-KEY request header when authorization is enabled. Sample key: 6B9F2A81D3E47C5A0B1F9E8D7C6B5A43.

Request Headers (all endpoints)

These headers apply to every API call in this document. They are not repeated in each endpoint example.

Header	Value	Required	Description
Content-Type	application/json	O/M	Required for POST requests when a JSON body is sent. GET requests may omit it; the runtime defaults to JSON when the header is absent.
X-API-KEY	string(32)	O	Authorization key configured in TMS (maximum 32 characters). Any client-generated format is accepted if it matches the TMS value. Sample: `6B9F2A81D3E47C5A0B1F9E8D7C6B5A43`. Required only when TMS authorization is enabled.

Request Types

Here are the transaction types for each function type used in the URL request path:

Function Type	HTTP Method	Transaction Type
Get Merchant List	GET / POST	merchantlist
Get Allowed Transactions	POST	getAllowedTransactions
Purchase	POST	transaction
Purchase Cash	POST	transaction
Cash Only	POST	transaction
Refund Amount	POST	transaction
MOTO Purchase	POST	transaction
MOTO Refund	POST	transaction
Pre-auth	POST	transaction
Pre-auth Complete	POST	transaction
Pre-auth Cancel (unattended only)	POST	transaction
Pre-auth Increment	POST	transaction
Pre-auth Delayed	POST	transaction
Reprint	POST	reprint
Card Verification	POST	querycard
Card Enquiry	POST	cardenquiry
Scan Code	POST	scancode
Settlement Enquiry	POST	settlement
Settlement Cutover	POST	settlement
Manual Host Logon	POST	logon
Pre-auth Inquiry	POST	transactionsearch
Pre-auth Completion Inquiry	POST	transactionsearch
Search Transaction	POST	transactionsearch
Cancel Transaction	GET / POST	canceltransaction
Health Check	GET	healthcheck
Bring App to Foreground	POST	bringapptoforeground
Query Transaction	GET	querytransaction
Query Stored Transaction	POST	querystoredtransaction
Approve Signature	POST	approvesignature
Extended Pre-auth	POST	transaction
Pre-auth Reversal	POST	transaction
Shift Totals	POST	shiftTotals
Voucher Entry	POST	voucherEntry

The routes above are the public endpoints documented by this page. Their behavior follows the terminal configuration and current operating state.

API Responses

Most endpoints return a JSON body with the same top-level shape. HTTP status and business outcome are separate: a 200 OK can still contain a declined transaction, and most non-2xx responses use the same envelope with error fields in Response. Health Check is the exception: it returns HTTP 200 with text/plain and a one-space body. Early transport validation errors (for example invalid SessionId length or unsupported Content-Type) may instead be returned as raw text/plain. This section describes the shared wrapper and the three response types the API returns.

Common response envelope

Most responses use this wrapper. The QA server serializes JSON responses with Content-Type: text/plain; clients should parse the body as JSON according to the endpoint contract. Endpoint-specific fields live inside Response.

Property	Type	M/O	Description
SessionId	string(36)	M	Echo of the `sessionId` from the request URI.
ResponseType	string	M	Identifies the operation that produced this response (e.g. `"transaction"`, `"logon"`, `"merchantlist"`). Matches the endpoint function — see API Requests → Request Types.
Response	object	M/O	Payload object. Normally present; the terminal may omit it for `getAllowedTransactions` when no merchant is supplied. Shape depends on `ResponseType` and outcome — see sections below and each endpoint page.

Boolean encoding rules are documented in Boolean Type. Use that setting when interpreting Success values in this section.

Choosing the response path

After parsing the envelope, use the fields inside Response to decide which path applies:

Response.ErrMessage is present → API error / exception (HTTP is non-2xx). Read ErrMessage and StatusCode, plus Suggestion when supplied. There is no Success field on this path.
Response.Success or Response.Transaction.Success is present → business outcome (HTTP is 200). Approved/completed vs declined/failed depends on the terminal's boolean encoding ("1"/"0" or true/false); read the endpoint's ResponseText or Response.Transaction.ResponseText on failure/decline.
Neither applies (e.g. merchantlist) → data payload only; HTTP 200 means the call succeeded.

HTTP status codes

The terminal sets the HTTP status on the wire. Response.StatusCode in the JSON body is the same value as a string (e.g. HTTP 403 → "StatusCode": "403").

HTTP	When	JSON `Response` shape
200	Request accepted; operation finished or data returned	Business fields — `Success`, `ResponseText`, `Transaction`, etc.
400	Invalid request data, bad `TxnType`, amount validation, malformed body	Usually `ErrMessage`, `StatusCode: "400"`; early transport validation may be raw `text/plain`
401	`X-API-KEY` missing or incorrect (when TMS authorization is enabled)	`ErrMessage`, `StatusCode: "401"`
403	Merchant validation failure or terminal busy	`ErrMessage`, `StatusCode: "403"`; `Suggestion` when supplied
500	Internal server error	May have no JSON body; some async operations defer the response until processing completes

How to read a response

HTTP status

200 — operation completed or data returned; check Success for approval vs decline.
400 / 401 / 403 — request rejected before processing; read Response.ErrMessage and Suggestion when supplied.
No response — connection failure or timeout; terminal app may be unreachable.

Business fields (HTTP 200)

Response.Success — true = success, false = failure (encoding per Boolean Type); read ResponseText on failure.
Response.Transaction.Success — same rule on transaction endpoints.
Async mode — poll Status / StatusText; see Sync vs Async.
Sync mode — the HTTP connection stays open until the terminal finishes and returns the full body.

Response types

1. Success (HTTP 200)

The operation completed. Where Success is present and true, result fields are populated. ResponseType matches the endpoint called (e.g. "transaction").

Example — approved transaction

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "transaction",
  "Response": {
    "Transaction": {
      "TxnType": "P",
      "Success": "1",
      "lAmount": 100,
      "lszApprovalCode": "327710",
      "szAuthorizationResponseCode": "00"
    }
  }
}

2. Business failure (HTTP 200)

The terminal processed the request but the operation did not succeed (declined card, user cancel, host decline, etc.). HTTP status is still 200 — this is not an API error. Check Success is false and read ResponseText (or Transaction.ResponseText). Do not use ErrMessage on this path.

Example — declined transaction

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "transaction",
  "Response": {
    "Transaction": {
      "TxnType": "P",
      "Success": "0",
      "ResponseText": "Transaction Declined"
    }
  }
}

3. Error / exception (HTTP 400 / 401 / 403)

The request was rejected before normal processing — invalid data, bad API key, invalid merchant, or terminal busy. The envelope is unchanged; ResponseType matches the endpoint called (e.g. "transaction" for POST .../transaction). Response contains ErrMessage, StatusCode, and optionally Suggestion — never Success or ResponseText.

Error response fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request transaction.
ResponseType	string(23)	M	Endpoint that was called (e.g. `"transaction"`, `"settlement"`, `"logon"`).
Response.ErrMessage	string	O	Error message — display to the operator.
Response.Suggestion	string	O	Optional recommended next action when supplied by the runtime.
Response.StatusCode	string	O	Same value as the HTTP status, as a string (e.g. `"403"`).

Common error cases (HTTP status as noted):

Payment-layer readiness failure (200) — POS Integration forwards a transaction for every valid merchant without a POS-side online/offline pre-check. If the Payment layer requires host logon, the Payment layer attempts automatic logon before continuing the original transaction. If logon succeeds, the original transaction continues; if it fails, read the normal business failure result (Response.Transaction for a completed synchronous transaction, or the async status/result when using AsyncMode).
Merchant validation failure (403) — the request cannot be resolved to a configured merchant (for example, an invalid merchant ID, or an omitted merchant when automatic selection is not possible).
Terminal busy (403) — another operation is in progress.
Invalid API key (401) — X-API-KEY header missing or wrong when TMS authorization is enabled.
Invalid request (400) — malformed JSON, invalid TxnType, or failed field validation.

Quick reference

Case	HTTP	Check
Approved transaction	200	`Response.Transaction.Success` = true
Declined transaction	200	`Response.Transaction.Success` = false; read `Response.Transaction.ResponseText` when present
Operation succeeded	200	`Response.Success` = true
Operation failed	200	`Response.Success` = false; read `ResponseText`
Payment-layer offline / host readiness failure	200	Read the normal transaction result or async status/result; do not treat it as an API error envelope
Merchant validation failure	403	`ErrMessage`, `StatusCode: "403"`; `Suggestion` when supplied
Terminal busy	403	`ErrMessage`, `StatusCode: "403"`
Invalid API key	401	`ErrMessage`, `StatusCode: "401"`
Invalid request	400	`ErrMessage`, `StatusCode: "400"`
Terminal unreachable	—	No HTTP response; use Health Check

Boolean Type

Boolean-like values are controlled by a TMS configuration.

The terminal uses one of two encodings for request and response bodies:

String mode — "1" / "0" (yes/no, enabled/disabled, approved/declined)
JSON boolean mode — true / false

Integrators must use the encoding that matches the terminal's TMS setting. Do not mix formats in a single request. Applies to Success, AsyncMode, WithReceiptImageData, and DisablePrinting (transaction, Card Verification, settlement), transaction flag fields (fAuthorized, fOffline, etc.), and other boolean switches documented on each endpoint.

POS Integration Options screen showing Boolean data format type configured in TMS

POS Integration Options — the Boolean data format type is configured on the terminal via TMS. Choose String 1/0 for "1"/"0" encoding or Boolean for true/false encoding in request and response bodies.

JSON examples in this document may show one encoding (string or boolean) for illustration; always match the terminal TMS setting in live integrations.

Build a Server Validation Handler

When the terminal's HTTP server uses TLS, the POS client connects over https:// instead of http://. A custom server validation handler and ca.pem CA certificate are required only when HTTP Server SSL Enabled is set to Yes in TMS (POS Integration Options). If SSL is disabled (No), use plain HTTP to the configured port — no CA file or TLS handler is needed.

HTTP Server SSL (TMS)

POS Integration Options screen showing HTTP Server SSL Enabled set to Yes in TMS

POS Integration Options — HTTP Server SSL Enabled controls whether the payment app serves the POS Integration API over HTTPS, while Enable SSL Certificate Verification controls whether the POS client validates the server certificate. Set both to Yes for HTTPS with certificate validation. When HTTP Server SSL Enabled is No, connections use HTTP only and certificate verification is not applicable.

When SSL is enabled, building a server validation handler ensures the client trusts the payment terminal by validating its certificate against a specific CA (Certificate Authority). This is typically required when:

A private CA signs the server's certificate.
Custom validation rules are required beyond default system certificate validation.
The handler replaces or supplements the system's default trusted Certificate Authorities with your custom CA.

Prerequisites

Apply the following only when HTTP Server SSL Enabled = Yes:

Store the provided ca.pem file in a secure and accessible location for the client.
Confirm the client can read and use the ca.pem file for validation.

Steps to implement the handler

When SSL is enabled on the terminal, follow these steps on the POS client:

Step 1 — Store the CA certificate
Save the ca.pem file in a secure location accessible by the client.

Step 2 — Implement the custom handler
Create a function or method that:

Reads the ca.pem file to load the CA certificate.
Configures a validation callback that reads the server's certificate chain during a TLS handshake.
Validates the server certificate against the loaded CA (ensure ca.pem matches the CA used to sign the server certificate).
Returns an object or structure for secure connections (e.g. HTTP clients).

Step 3 — Use the handler in connections
Use the custom handler when establishing HTTPS connections to the terminal so the server certificate is validated against your CA.

Get Merchant List

Retrieves the list of configured merchants from the terminal. This request has no request body — all parameters are passed via headers only.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request transaction.
ResponseType	string	M	Always `"merchantlist"`.
Merchants	array	M	Array of merchant objects, each containing Id, Name, and Mode.
Id	string(2)	M	Merchant identifier.
Name	string	M	Merchant display name.
Mode	string	M	Merchant mode. Some possible values are mentioned in Table ENUM-10.

Table ENUM-10 — Mode field values

Enum table — colocated with Get Merchant List. Also in Table Index.

Here are some values for the Mode field.

Value of "Mode" field
None
LogOff
EOV
Online
RKIFail

Endpoint

GET/POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/merchantlist

No request body required

Response Example

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "merchantlist",
  "Response": {
    "Merchants": [
      {
        "Id": "1",
        "Name": "Main Merchant",
        "Mode": "Online"
      },
      {
        "Id": "2",
        "Name": "Second Merchant",
        "Mode": "LogOff"
      }
    ]
  }
}

Get Allowed Transactions

Returns the transaction types enabled for a merchant on this terminal (purchase, refund, pre-auth, etc.). Use this to build dynamic menus or validate TxnType before calling transaction.

Request Body Fields

Field Name	Type (Max Length)	M/O	Description
Merchant	string(2)	O	Merchant to query. Send it explicitly when the function list is required. When omitted, the terminal may return HTTP 200 with only `SessionId` and `ResponseType` and no `Response` payload.

Response Fields

Field Name	Type (Max Length)	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"getAllowedTransactions"`.
Merchant	string(2)	O	Echo of the resolved merchant when one is supplied or selected.
FunctionItems	array	O	List of allowed function entries for the resolved merchant. Omitted when no merchant is supplied and the terminal returns an empty envelope.
Id	int	M	Function identifier (on each `FunctionItems` element).
ParentId	int	M	Parent function identifier (on each `FunctionItems` element).

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/getAllowedTransactions

Request Example

{
  "Merchant": "01"
}

Response Example

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "getAllowedTransactions",
  "Response": {
    "Merchant": "01",
    "FunctionItems": [
      { "Id": 1, "ParentId": 0 },
      { "Id": 42, "ParentId": 1 }
    ]
  }
}

Health Check

Verifies that the terminal's payment app server is alive and reachable. The POS can send this request in parallel with active transactions without interference.

A successful response returns HTTP 200 with Content-Type: text/plain, Content-Length: 1, and a single-space body. No response (connection refused/timeout) indicates the server is down.

Endpoint

GET https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/healthcheck

No request body required

Response

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 1

(one space — server is alive)

Bring App to Foreground

This function moves the payment app to the foreground if it is running in the background.

The request to bring the application to the foreground uses the POST method and does not require a request body to perform this function.

Response Fields

Below is a list of fields that will appear in the 'Bring Application to Foreground' response. Fields labeled with 'M' (Mandatory) appear whether the request succeeds or fails.

Field Name	Type (Max Length)	M/O	Description
SessionId	string(36)	M	SessionId of the request transaction.
ResponseType	string(23)	M	ResponseType is the TransactionType of the requested transaction (`"bringapptoforeground"`).
Success	bool	M	Whether the operation succeeded (true) or failed (false).
ResponseText	string	O	Text of Response. Commonly occurs when a transaction is declined.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/bringapptoforeground

No request body required

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "bringapptoforeground",
  "Response": {
    "Success": "1",
    "ResponseText": "Application brought to the foreground"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "bringapptoforeground",
  "Response": {
    "Success": "0",
    "ResponseText": "Application is not allowed to bring itself to the foreground"
  }
}

Transaction

All financial transaction types use POST /v1/sessions/{{sessionId}}/transaction with the same request and response structure. Set TxnType to identify the operation — see subsections below (Purchase, Refund, Pre-auth, etc.).

Fields marked with M (Mandatory) must be assigned values. The Amount must be greater than 0 where applicable. Numbered lookup tables are grouped under Request field logic, Response field logic, and Field Enums — or use the Table Index.

Common Request Fields

Field Name	Type (Max Length)	M/O	Description
Merchant	string(2)	O	Specify the merchant to execute the transaction. See Table REQ-01.
TxnType	string(3)	M	Type of transaction — value depends on operation (see subsections).
Amount	long	O	Transaction amount in cents. Required and greater than 0 for amount-based transaction types; optional for Extended Pre-auth (`PE`).
TxnRef	string(64)	O	Reference number attached to the transaction. Appears on the receipt.
OrderID	string(51)	O	Client-supplied order identifier for later lookup via Query Stored Transaction. The current native buffer reserves 52 bytes including the terminator, so 51 data characters are the safe maximum. The terminal echoes it in `Response.Transaction.OrderID` when present and does not generate one when omitted.
EnableTip	bool	O	Whether tip entry is offered. Default disabled.
AmtTip	long	O	Tip amount of the sale in cents.
AsyncMode	bool	O	Default disabled. Set enabled for async mode — see Sync vs Async.
WithReceiptImageData	bool	O	Requests supplementary receipt image/signature data. `ReceiptData` is controlled by `ReceiptType`; receipt fields are optional and returned only when generated.
DisablePrinting	bool	O	If enabled, disable receipt printing for this transaction. Exception: when the transaction requires a paper signature, the merchant signature copy is still printed so the cardholder can sign. All other receipts stay unprinted, and the receipt data returned to the POS is unchanged.
ReceiptType	int	O	Defines the receipt format. See Table REQ-02.
PlainTextCharPerLine	int	O	Plain-text receipt width when `ReceiptType` is plain text.
CustomerReceiptPrintOption	int	O	Defines the customer receipt printing option. See Table REQ-03.
MerchantReceiptPrintOption	int	O	Defines the merchant receipt printing option. See Table REQ-03.

EnableTip behavior

If AmtTip > 0, the request is sent with the Tip value regardless of EnableTip.
If AmtTip is 0 and EnableTip is true and the payment app allows tip, a popup prompts the user to enter a Tip value.
If the payment app is not set up to allow tip, the request proceeds without a Tip value.

Disabled functions and manual card entry

If the requested transaction type is disabled for the merchant in TMS, the terminal rejects the request without contacting the host. The response is HTTP 200 with the requested TxnType, Success "0" and ResponseText "This Feature Is Not Available".
If MOTO is disabled for the merchant, a transaction request that asks for manual card entry (for example with Pan) is rejected with the same response.
If the MOTO password is enabled for the merchant, pressing Manual Entry on the terminal card screen asks for the MOTO password before the card details are entered. This applies to Purchase, Pre-auth, Pre-auth Complete and Card Verification. Refund does not ask for it, and MOTO Purchase asks for it only once, as before.
Back on the MOTO password prompt returns to the card screen. Cancel, closing the prompt, or reaching the maximum number of wrong attempts cancels the transaction with Success "0" and ResponseText "Transaction Cancelled". An idle timeout on the prompt ends the transaction with Success "0" and ResponseText "Dialog Timed Out".

Reference — Request field logic

Lookup tables for common request fields — each table is linked from the matching row in Common Request Fields. See also Table Index.

Table REQ-01 — Merchant field logic

Merchant Field Value	Single Merchant	Multi Merchant
Not set or invalid (null, "0", "abc", etc.)	Automatically select the default merchant	Return error – Merchant Id not found
Valid value (parsable to int)	Use the selected merchant	Use the selected merchant

Table REQ-02 — ReceiptType field logic (request)

ReceiptType Value	Description
Not set	Uses TMS default.
0	Do not return receipt data.
1	Return receipt in HTML format.
2	Return receipt in plain text format.
Others	Treated as 'Not Set' value.

Table REQ-03 — Print Option (CustomerReceiptPrintOption / MerchantReceiptPrintOption)

Defines the receipt printing behavior for customer and merchant during a transaction.

Print Option	Description
Not set	Follows the terminal receipt configuration.
0	No Printing
1	AutoPrinting
2	Prompt Printing

Transaction Response

The outer response contains SessionId, ResponseType, and Response. For a financial transaction, transaction fields are nested under Response.Transaction. Fields labeled M appear when the native transaction model supplies them; optional fields may be omitted by transaction type or outcome. Search results use a separate Response.Transactions[] item model described below.

In the table below, SessionId and ResponseType are outer-envelope fields; Success and every transaction detail field are under Response.Transaction.

Field Name	Type (Max Length)	M/O	Description
SessionId	string(36)	M	SessionId of the request transaction.
ResponseType	string(23)	M	Operation response type. For financial transactions this is `"transaction"`; the transaction subtype is returned in `TxnType`.
Success	bool	M	Whether the transaction is approved (true) or declined (false).
ResponseText	string	O	Text of Response. Commonly occurs when a transaction is declined.
PrinterStatus	string	O	Printer state text returned by the terminal when available.
ReceiptType	int	M	Indicates the receipt format returned. See Table RES-01.
Merchant	string(2)	O	Merchant that executed the transaction.
TxnType	string(9)	M	Type of transaction (matches request `TxnType`).
OrderID	string(51)	O	Order identifier echoed from the original request. The current native buffer reserves 52 bytes including the terminator, so 51 data characters are the safe maximum. Present only when the original request supplied `OrderID`.
IdShift	uint	M	Shift identifier.
IdShiftName	uint	M	Shift name identifier.
lAmount	long	M	The approved amount.
lTipAmount	long	M	The approved tip amount.
lCashOut	long	M	The approved cash amount.
lCashOutFee	long	M	The cash-out transaction fee.
lSurChargeTax	long	M	The tax surcharge.
lDiscount	long	M	Discount amount of the transaction.
lDiscountPercent	long	M	Discount percentage of the transaction.
iReward	uint	M	The transaction reward.
lAuthorizedTotal	long	M	The total approved amount: `lAmount + lTipAmount + lCashOut + fees/surcharges - discounts`, where applicable.
lDonationAmount	long	M	The total approved donation amount.
iEntryMode	uint	M	Entry mode. See Table ENUM-04.
iCardType	uint	M	Type of card. See Table ENUM-03.
iCurrencyCode	uint	M	The currency code.
fsModify	uint	M	The current status of the payment record. See Table ENUM-01.
iPaymentType	uint	M	The payment type. See Table ENUM-05.
iCustomerLanguage	uint	M	The customer language. See Table ENUM-06.
fClosed	short	M	Whether the transaction has been completed.
fBatchError	short	M	Whether the batch is in an error state.
fVoided	short	M	Whether the transaction has been voided.
fRefunded	bool	M	Whether the transaction has been refunded.
fAuthorized	bool	M	Whether the payment record has been processed by the host.
fSignature	bool	M	Whether the transaction is a signature transaction.
fCardHolderStatesCVVnotOnCard	bool	M	Whether the CVV is absent because the cardholder states there is no CVV on the card ("No CVV On Card").
fCardNotPresent	bool	M	Whether the CVV is absent because it is not present ("CVV Not Present").
fCardNotPresentMail	bool	M	Whether the transaction is a card-not-present mail order.
fCardNotPresentPhone	bool	M	Whether the transaction is a card-not-present telephone order.
fCanAdjust	bool	M	Whether the transaction can be adjusted.
fCanVoid	bool	M	Whether the transaction can be voided.
fCanPreAuthTopUp	bool	M	Whether a pre-auth increment can be performed on the transaction.
fCanPreAuthComplete	bool	M	Whether the pre-auth can be completed.
fCanVoidPreAuthComplete	bool	M	Whether the pre-auth completion can be voided.
fCanGoOffline	bool	M	Whether the transaction can be processed offline using store-and-forward.
fOffline	bool	M	Indicates whether the transaction is from an EOV (or OFFLINE) case or an ONLINE case. If `fOffline` is true, the transaction is from an EOV (or OFFLINE) case; otherwise, the transaction is ONLINE.
lszCustomerReference	string	O	Customer reference number from the payment record.
szReferenceNumber	string	O	Retrieval Reference Number (RRN) assigned to the transaction. This is different from `lszCustomerReference`, which contains the POS/customer transaction reference (`TxnRef`).
lszReferenceNumberKey	string	O	Reference number search key.
lszApprovalCodeKey	string	O	Approval code search key.
lszSequenceNumber	string	O	Sequence number from the payment record.
Date	string(8)	O	Date used for searching, formatted as `YYYYMMDD`.
Time	string(10)	O	Time used for searching, formatted as `hh:mm:ss`.
AuthorizationExpiryDate	string(8)	O	Authorization expiry date. Formatted as `YYYYMMDD`.
szAuthorizationResponseCode	string	M	The approval response code of the transaction.
lszApprovalCode	string	O	The approval code of the transaction.
lszSTAN	string	O	The System Trace Audit Number of the transaction.
TRV	string(15)	O	Transaction reference value.
IssuerRRN	string(15)	O	Issuer retrieval reference number.
szIssuerId	string	O	Issuer identifier.
szCardHolderName	string	O	Cardholder name.
szStreet	string	O	Cardholder street address (MOTO).
szApartment	string	O	Cardholder apartment (MOTO).
szZipCode	string	O	Cardholder postal code (MOTO).
iReversalReason	uint	M	The reason for reversal. See Table ENUM-07.
szProcessedLaterNumber	string	O	Processed-later reference number when applicable.
lszCardLogo	string	M	Card logo.
szQRCode	string	O	URL of the stored transaction receipt.
byPinType	byte	M	PIN type. See Table ENUM-08.
byPinStatus	byte	M	PIN status. See Table ENUM-09.
iNoCVVOption	uint	M	The reason no CVV was provided.
byCDCVM	byte	M	The CDCVM (Consumer Device Cardholder Verification Method) value of the card.
iAccountType	uint	M	The account type of transaction. See Table ENUM-02.
lszEndCardNumber	string	O	The last four digits of the card number used to perform this transaction.
szMaskedCardNumber	string	O	Masked card number returned when available.
cardHash	string	O	Hash of the card details when returned by the terminal.
szCardType	string(34)	O	Card type description string from the presented card (e.g. `"Mastercard"`).
lServiceFees	long	O	The surcharge fee for the transaction. Only shown when it has a value.
lFee	long	O	The fee for the transaction. Only shown when it has a value.
PID	uint	O	ID of payment.
ReceiptData	string	O	Contains the receipt data of the transaction.
ReceiptLogo	string	O	Contains the logo to be printed on the receipt.
DigitalSig	string	O	Contains the digital signature data to be printed on the receipt.

Reference — Response field logic

Lookup tables for response fields — linked from Transaction Response and reused by Search and Card Verification responses.

Table RES-01 — ReceiptType field logic (response)

ReceiptType Value	Description
0	Do not return receipt data.
1	Return receipt in HTML format.
2	Return receipt in plain text format.

Reference — Field Enums

Enum value tables for transaction response fields. Each table is linked from the matching row in Transaction Response. Jump: ENUM-01 · ENUM-02 · ENUM-03 · ENUM-04 · ENUM-05 · ENUM-06 · ENUM-07 · ENUM-08 · ENUM-09

Table ENUM-01 — fsModify field values

Value of "fsModify" field
PAYMENT_MODIFY_ADJUST = 0x00000001
PAYMENT_MODIFY_VOID = 0x00000002
PAYMENT_MODIFY_PARTIALVOID = 0x00000004
PAYMENT_MODIFY_REVERSED = 0x00000008
PAYMENT_MODIFY_STOREFORWARD = 0x00000010
PAYMENT_MODIFY_PENDING = 0x00000020
PAYMENT_MODIFY_OFFLINE = 0x00000100
PAYMENT_MODIFY_PARTIALPREAUTHCOMPLETE = 0x00000200
PAYMENT_MODIFY_PREAUTHCOMPLETE = 0x00000400
PAYMENT_MODIFY_DELAYEDPREAUTHCOMPLETE = 0x00000800
PAYMENT_MODIFY_EOV = 0x00001000
PAYMENT_MODIFY_PENDING_CANCELFAIL = 0x00002000
PAYMENT_MODIFY_EMV_ERROR = 0x40000000
PAYMENT_MODIFY_CANCELLED = 0x80000000

Table ENUM-02 — iAccountType field values

Value of "AccountType" field
ACCOUNT_TYPE_SAVINGS = "0"
ACCOUNT_TYPE_CHEQUE = "1"
ACCOUNT_TYPE_CREDIT = "2"

Table ENUM-03 — iCardType field values

Here are some values for the iCardType field.

CardType	CardType
CARD_NONE = 0	CARD_UNIONPAY = 75
CARD_DEBIT = 1	CARD_TROY = 76
CARD_VISADEBIT = 2	CARD_SPARE1 = 77
CARD_DEBITMASTER = 3	CARD_SPARE2 = 78
CARD_AMEXDEBIT = 4	CARD_SPARE3 = 79
CARD_JCBDEBIT = 5	CARD_SPARE4 = 80
CARD_DISCOVERDEBIT = 6	CARD_SPARE5 = 81
CARD_UNIONPAYDEBIT = 7	CARD_SPARE6 = 82
CARD_INTERACTDEBIT = 8	CARD_SPARE7 = 83
CARD_MAESTRODEBIT = 9	CARD_SPARE8 = 84
CARD_TROYDEBIT = 10	CARD_SPARE9 = 85
CARD_SPAREDEBIT1 = 11	CARD_SPARE10 = 86
CARD_SPAREDEBIT2 = 12	CARD_SPARE11 = 87
CARD_SPAREDEBIT3 = 13	CARD_SPARE12 = 88
CARD_SPAREDEBIT4 = 14	CARD_SPARE13 = 89
CARD_SPAREDEBIT5 = 15	CARD_SPARE14 = 90
CARD_SPAREDEBIT6 = 16	CARD_SPARE15 = 91
CARD_SPAREDEBIT7 = 17	CARD_SPARE16 = 92
CARD_SPAREDEBIT8 = 18	CARD_SPARE17 = 93
CARD_SPAREDEBIT9 = 19	CARD_SPARE18 = 94
CARD_SPAREDEBIT10 = 20	CARD_SPARE19 = 95
CARD_ALLIEDPDEBIT = 21	CARD_SPARE20 = 96
CARD_ARBUCKLEDEBIT = 22	CARD_ALLIEDP = 97
CARD_ASBPRVLBDEBIT = 23	CARD_ARBUCKLE = 98
CARD_ATSDEBIT = 24	CARD_ASBPRVLB = 99
CARD_BABYCITYDEBIT = 25	CARD_ATS = 100
CARD_BARTRCRDDEBIT = 26	CARD_BABYCITY = 101
CARD_CASHRWDSDEBIT = 27	CARD_BARTRCRD = 102
CARD_CRTDEBIT = 28	CARD_CASHRWDS = 103
CARD_CSLDEBIT = 29	CARD_CRT = 104
CARD_DRIVEDEBIT = 30	CARD_CSL = 105
CARD_EAZYCDDEBIT = 31	CARD_DRIVE = 106
CARD_ECARDDEBIT = 32	CARD_EAZYCD = 107
CARD_ECARDZGDEBIT = 33	CARD_ECARD = 108
CARD_ECARDZLDEBIT = 34	CARD_ECARDZG = 109
CARD_ECOM1DEBIT = 35	CARD_ECARDZL = 110
CARD_EFTPOSDEBIT = 36	CARD_ECOM1 = 111
CARD_ELOYALTYDEBIT = 37	CARD_EFTPOS = 112
CARD_EZIPAYDEBIT = 38	CARD_ELOYALTY = 113
CARD_FFCARDDEBIT = 39	CARD_EZIPAY = 114
CARD_FLEETDEBIT = 40	CARD_FFCARD = 115
CARD_FLYBUYDEBIT = 41	CARD_FLEET = 116
CARD_FPFGIFTDEBIT = 42	CARD_FLYBUY = 117
CARD_GENIEDEBIT = 43	CARD_FPFGIFT = 118
CARD_GIFTSTNDEBIT = 44	CARD_GENIE = 119
CARD_INDUEDEBIT = 45	CARD_GIFTSTN = 120
CARD_INSIGHTDEBIT = 46	CARD_INDUE = 121
CARD_LOYALTYDEBIT = 47	CARD_INSIGHT = 122
CARD_MOBILDEBIT = 48	CARD_MOBIL = 123
CARD_MTAGIFTDEBIT = 49	CARD_MTAGIFT = 124
CARD_NPDDEBIT = 50	CARD_NPD = 125
CARD_ONECARDDEBIT = 51	CARD_ONECARD = 126
CARD_POSTIEDEBIT = 52	CARD_POSTIE = 127
CARD_QCARDDEBIT = 53	CARD_QCARD = 128
CARD_RD1DEBIT = 54	CARD_RD1 = 129
CARD_ROCKGASDEBIT = 55	CARD_ROCKGAS = 130
CARD_STARCARDDEBIT = 56	CARD_STARCARD = 131
CARD_SWIPEGFTDEBIT = 57	CARD_SWIPEGFT = 132
CARD_SWIPELOYDEBIT = 58	CARD_SWIPELOY = 133
CARD_TRUREWRDDEBIT = 59	CARD_TRUREWRD = 134
CARD_TTCRDSDEBIT = 60	CARD_TTCRDS = 135
CARD_TTLSTOREDEBIT = 61	CARD_TTLSTORE = 136
CARD_VIIDEBIT = 62	CARD_VII = 137
CARD_WAPDEBIT = 63	CARD_WAP = 138
CARD_WESTFLDDEBIT = 64	CARD_WESTFLD = 139
CARD_WPGDEBIT = 65	CARD_WPG = 140
CARD_ZBIZDEBIT = 66	CARD_ZBIZ = 141
CARD_ZCARDDEBIT = 67	CARD_ZCARD = 142
CARD_CREDIT = 68	CARD_GIFT = 143
CARD_VISA = 69	CARD_LOYALTY = 144
CARD_MASTER = 70	CARD_CASH = 145
CARD_AMEX = 71	CARD_CHEQUE = 146
CARD_JCB = 72	CARD_EBTASSIST = 147
CARD_DINERS = 73	CARD_EBTSNAP = 148
CARD_DISCOVER = 74	AllCards = 149
CARD_UNKNOWN = 150	CARD_ZBIZTESTDEBIT = 151
CARD_ZBIZTEST = 152

Table ENUM-04 — EntryMode / iEntryMode field values

Used in Transaction Response (iEntryMode) and Card Verification response (EntryMode).

Value	Name
0	EM_NONE
1	EM_POS
2	EM_IMPRINT
3	EM_MOTO
4	EM_SWIPED
5	EM_MANUAL
6	EM_RFID
7	EM_CONTACTLESS_ISO
8	EM_CONTACTLESS_MAGSTRIPE
9	EM_CONTACTLESS_DOMESTIC
10	EM_CONTACTLESS_NFC
11	EM_CONTACTLESS_VAS
12	EM_SMC
13	EM_ALIPAY
14	EM_WECHAT
15	EM_END
16	EM_ECOMMERCE
17	EM_CENTRAPAY
18	EM_GIFT_REDEEM
19	EM_DIRECTPAY

Table ENUM-05 — iPaymentType field values

Payment Type	Payment Type
PAYMENT_TYPE_SALE = 0	PAYMENT_TYPE_PREAUTHTOPUP = 12
PAYMENT_TYPE_REFUND = 1	PAYMENT_TYPE_PREAUTHDELAY = 13
PAYMENT_TYPE_CASHADVANCE = 2	PAYMENT_TYPE_PREAUTHPARTIAL = 14
PAYMENT_TYPE_PREAUTH = 3	PAYMENT_TYPE_PREAUTHCANCEL = 15
PAYMENT_TYPE_PREAUTHCOMPLETE = 4	PAYMENT_TYPE_IMPRINTER = 20
PAYMENT_TYPE_BALANCEINQUIRY = 5	PAYMENT_TYPE_AUTHONLY = 60
PAYMENT_TYPE_DEPOSIT = 6	PAYMENT_TYPE_REGISTER = 100
PAYMENT_TYPE_SETTLE = 7	PAYMENT_TYPE_ACTIVATE = 101
PAYMENT_TYPE_INSTALLMENTSALE = 10	PAYMENT_TYPE_DEACTIVATE = 102
PAYMENT_TYPE_LATEINTERESTINSTALLMENTSALE = 11	PAYMENT_TYPE_RELOAD = 103
PAYMENT_TYPE_REDEEMED = 104

Table ENUM-06 — iCustomerLanguage field values

Locale code → language name → numeric value (payment app locale catalog; default supported locale is en_US = 1).

Locale	Language	Value
en_US	English (US)	1
de_DE	German (Germany)	2
zh_CN	Chinese (PRC)	3
zh_TW	Chinese (Taiwan)	4
cs_CZ	Czech (Czech Republic)	5
nl_BE	Dutch (Belgium)	6
en_AU	English (Australia)	7
en_GB	English (Britain)	8
en_CA	English (Canada)	9
en_NZ	English (New Zealand)	10
en_SG	English (Singapore)	11
fr_BE	French (Belgium)	12
fr_CA	French (Canada)	13
fr_FR	French (France)	14
fr_CH	French (Switzerland)	15
de_AT	German (Austria)	16
de_LI	German (Liechtenstein)	17
de_CH	German (Switzerland)	18
it_IT	Italian (Italy)	19
it_CH	Italian (Switzerland)	20
ja_JP	Japanese (Japan)	21
ko_KR	Korean (Korea)	22
pl_PL	Polish (Poland)	23
ru_RU	Russian (Russia)	24
es_ES	Spanish (Spain)	25
ar_EG	Arabic (Egypt)	26
ar_IL	Arabic (Israel)	27
bg_BG	Bulgarian (Bulgaria)	28
ca_ES	Catalan (Spain)	29
hr_HR	Croatian (Croatia)	30
da_DK	Danish (Denmark)	31
en_IN	English (India)	32
fi_FI	Finnish (Finland)	33
en_IE	English (Ireland)	34
en_ZA	English (South Africa)	35
el_GR	Greek (Greece)	36
iw_IL	Hebrew (Israel)	37
hi_IN	Hindi (India)	38
hu_HU	Hungarian (Hungary)	39
in_ID	Indonesian (Indonesia)	40
lt_LT	Lithuanian (Lithuania)	41
lv_LV	Latvian (Latvia)	42
nb_NO	Norwegian Bokmål (Norway)	43
pt_BR	Portuguese (Brazil)	44
sr_RS	Serbian (Cyrillic, Serbia)	45
sk_SK	Slovak (Slovakia)	46
sl_SI	Slovenian (Slovenia)	47
es_US	Spanish (US)	48

Table ENUM-07 — iReversalReason field values

Value
AUTO_REVERSAL_POWERFAILURE = 1
AUTO_REVERSAL_SIGNATURE = 2
AUTO_REVERSAL_NETWORK = 3
AUTO_REVERSAL_MACVALIDATION = 4
AUTO_REVERSAL_MESSAGEVALIDATION = 5
AUTO_REVERSAL_INVALIDRESPONSECODE = 6
AUTO_REVERSAL_POWERLINKFAILURE = 7
AUTO_REVERSAL_TRANSACTIONVOID = 8
AUTO_REVERSAL_INTERNALDEVICEFAILURE = 9
AUTO_REVERSAL_CARDREMOVED = 10
AUTO_REVERSAL_CARDDECLINED = 11

Table ENUM-08 — byPinType field values

Value
PIN_TYPE_NO_PIN = 0
PIN_TYPE_ONLINE = 1
PIN_TYPE_OFFLINE_PLAINTEXT = 2
PIN_TYPE_OFFLINE_ENCRYPTED = 3

Table ENUM-09 — byPinStatus field values

Value
PIN_NOT_PROMPTED = 0
PIN_PROMPTED_AND_CANCELLED = 1
PIN_PROMPTED_AND_TIMEDOUT = 2
PIN_PROMPTED_AND_ENTERED = 3
PIN_PROMPTED_AND_BYPASSED = 4

Endpoint (all transaction types)

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/transaction

Generic Request Example (Purchase)

{
  "Merchant": "01",
  "TxnType": "P",
  "EnableTip": 1,
  "AmtTip": 100,
  "Amount": 200,
  "TxnRef": "12345567890",
  "OrderID": "order-20260905-001",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Approved
Declined
{
  "SessionId": "12345678901",
  "ResponseType": "transaction",
  "Response": {
    "Transaction": {
      "ReceiptType": 1,
      "ReceiptData": "...",
      "PID": 6,
      "OrderID": "order-20260905-001",
      "Merchant": "1",
      "TxnType": "P",
      "Success": "1",
      "IdShift": 1,
      "IdShiftName": 0,
      "lAmount": 200,
      "lTipAmount": 100,
      "lCashOut": 0,
      "lCashOutFee": 0,
      "lSurChargeTax": 0,
      "lDiscount": 0,
      "lDiscountPercent": 0,
      "iReward": 0,
      "lAuthorizedTotal": 300,
      "lDonationAmount": 0,
      "iEntryMode": 7,
      "iCardType": 69,
      "iAccountType": 2,
      "iCurrencyCode": 36,
      "fsModify": 0,
      "iPaymentType": 0,
      "iCustomerLanguage": 1,
      "fClosed": 0,
      "fBatchError": 0,
      "fVoided": 0,
      "fRefunded": "0",
      "fAuthorized": "0",
      "fSignature": "0",
      "iCVVStatus": 0,
      "iMotoOrderType": 0,
      "fCanAdjust": "1",
      "fCanVoid": "1",
      "fCanPreAuthTopUp": "0",
      "fCanPreAuthComplete": "1",
      "fCanVoidPreAuthComplete": "0",
      "fCanGoOffline": "0",
      "lszCustomerReference": "12345567890",
      "Date": "20260905",
      "Time": "18:16:26",
      "szAuthorizationResponseCode": "00",
      "lszApprovalCode": "68550A",
      "szReferenceNumber": "000001007664",
      "lszSTAN": "007664",
      "lszEndCardNumber": "8770",
      "iReversalReason": 0,
      "szQRCode": "https://receipt.project-jump-start.com/PX60082420260509181626WIJLpzy.html",
      "byPinType": 1,
      "byPinStatus": 3,
      "iNoCVVOption": 0,
      "byCDCVM": 0,
      "szMaskedCardNumber": "472674******8770",
      "cardHash": "a101cd4d84c5eca7ed4b1c9617d5d0ffda37049e7b6211d7e58b146cdac7e1b4"
    }
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "transaction",
  "Response": {
    "Transaction": {
      "TxnType": "P",
      "Success": "0",
      "ResponseText": "Transaction Declined",
      "lAmount": 0,
      "lAuthorizedTotal": 0,
      "ReceiptType": 1
    }
  }
}

Response examples apply to all transaction types. Only TxnType and populated fields differ.

Transaction Types

Purchase TxnType: `P`

The purchase transaction type allows the merchant to perform a sale. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"P"` (Purchase).
Amount	long	M	Amount of sale in cents. Must be greater than 0.
EnableTip	bool	O	Whether tip entry is offered. Default disabled. See EnableTip notes.
AmtTip	long	O	Tip amount of the sale in cents.

Request Example — Purchase

{
  "Merchant": "01",
  "TxnType": "P",
  "EnableTip": 1,
  "AmtTip": 100,
  "Amount": 200,
  "TxnRef": "12345567890",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Refund Amount TxnType: `R`

The refund transaction type allows the merchant to refund a sale. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"R"` (Refund Amount).
Amount	long	M	Refund amount in cents. Must be greater than 0.

Request Example — Refund Amount

{
  "Merchant": "01",
  "TxnType": "R",
  "Amount": 1000,
  "TxnRef": "{{txnRef}}",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Cash Only TxnType: `C`

The cash-out transaction type allows the merchant to perform a cash-out transaction. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"C"` (Cash Only).
Amount	long	M	Cash amount in cents. Must be greater than 0.

Request Example — Cash Only

{
  "Merchant": "01",
  "TxnType": "C",
  "Amount": 10000,
  "TxnRef": "{{txnRef}}",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Purchase Cash TxnType: `PC`

The purchase cash transaction type allows the merchant to perform a sale and also withdraw cash. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PC"` (Purchase Cash).
Amount	long	M	Purchase amount in cents. Must be greater than 0.
AmtCash	long	M	Cash-out amount in cents. Must be greater than 0.

Request Example — Purchase Cash

{
  "Merchant": "01",
  "TxnType": "PC",
  "Amount": 1000,
  "AmtCash": 2000,
  "TxnRef": "{{txnRef}}",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

MOTO Purchase TxnType: `MP`

The MOTO Purchase transaction type allows the merchant to perform a sale with a manually entered transaction that has been generated from a mail order or a telephone order. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"MP"` (MOTO Purchase).
Amount	long	M	Amount in cents. Must be greater than 0.
EnableTip	bool	O	Whether tip entry is offered. Default disabled.
AmtTip	long	O	Tip amount of the sale in cents.
Pan	string(20)	O	Card number. If omitted, operator enters on terminal.
DateExpiry	string(4)	O	Card expiry in `MMYY` format.
CVV	string(3)	O	Card CVV/CVC.
CardName	string(26)	O	Cardholder name.

Request Example — MOTO Purchase

{
  "Merchant": "01",
  "TxnType": "MP",
  "TxnRef": "{{txnRef}}",
  "EnableTip": 1,
  "AmtTip": 200,
  "Amount": 2000,
  "Pan": "6367172100001111",
  "DateExpiry": "1249",
  "CVV": "120",
  "CardName": "Paymark Test",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

MOTO Refund TxnType: `MR`

The MOTO Refund transaction type allows the merchant to refund a sale with a manually entered transaction. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"MR"` (MOTO Refund).
Amount	long	M	Refund amount in cents. Must be greater than 0.
Pan	string(20)	O	Card number.
DateExpiry	string(4)	O	Card expiry in `MMYY`.
CardName	string(26)	O	Cardholder name.
CVV	string(3)	O	Card CVV.

Request Example — MOTO Refund

{
  "Merchant": "01",
  "TxnType": "MR",
  "Amount": 100,
  "TxnRef": "{{txnRef}}",
  "Pan": "6367172100001111",
  "DateExpiry": "1249",
  "CardName": "Paymark Test",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Pre-auth Family

Pre-auth Family — Developer Guide

Pre-auth reserves funds on the card without capturing the final amount. Most follow-up operations reference the original authorization using lszApprovalCode, RRN, and lszSTAN; unattended-only PAC uses lszApprovalCode and RRN without lszSTAN. Provide the original RRN and set lszSTAN to its last six characters when required. All pre-auth transactions use the same transaction request format and share the transaction response structure.

Typical flow

Step	TxnType	What it does	Source record
1	PA	Authorize — reserve funds on the card.	—
2a	AC	Complete — capture the final amount.	Original `PA` (`FuncType: PreAuthInquiry`)
2b	PAC	Cancel the open pre-auth — unattended mode only.	Original `PA` (`FuncType: PreAuthInquiry`)
2c	PT	Increment — increase the reserved amount.	Original `PA` (`FuncType: PreAuthInquiry`)
2d	PR	Reversal — reverse the open pre-auth.	Original `PA` (`FuncType: PreAuthInquiry`)
2e	PE	Extended — extend the legacy pre-auth record.	Original `PA` (`FuncType: PreAuthInquiry`)
3	PD	Delayed — optional adjustment after completion when extra goods/services are delivered.	Original `AC` (`FuncType: PreAuthCompleteInquiry`)

Linking follow-up requests

AC, PT, PD, PE, and PR require lszApprovalCode, the original RRN, and lszSTAN set to the last six characters of the original RRN. PAC is unattended-only and requires the original RRN and lszApprovalCode; Amount and lszSTAN are not required by the current runtime.

Option 1 — Search Transaction: Use the original RRN and approval code as AuthId with the correct FuncType, then select the matching record from Response.Transactions[].
Option 2 — POS-managed: Store lszApprovalCode and szReferenceNumber (RRN) for PAC; store lszApprovalCode, lszSTAN, and szReferenceNumber for the other follow-up requests, then pass the required fields in the follow-up request.

Search Transaction ↔ Pre-auth

Use Search Transaction to list matching records on the terminal before performing a follow-up:

FuncType: "PreAuthInquiry" — look up an original pre-auth for Complete, Cancel, Increment, Extended, or Reversal.
FuncType: "PreAuthCompleteInquiry" — look up a completed pre-auth for Delayed.

FuncType is mandatory. For either pre-auth inquiry type, both RRN and AuthId are mandatory; AuthId must equal the original transaction's lszApprovalCode. Stan is optional; when supplied, use the last six characters of RRN.

Pre-auth TxnType: `PA`

The pre-auth transaction type allows the merchant to pre-authorize a sale. It uses the transaction request format.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PA"` (Pre-auth).
Amount	long	M	Pre-auth amount in cents. Must be greater than 0.
IsMaxAmount	bool	O	When enabled, use the maximum amount configured in MaxStore for the unattended pre-auth.

MaxStore maximum amount configuration for IsMaxAmount

MaxStore maximum amount configuration — the Unattended Max Amount setting used when IsMaxAmount is enabled.

After approval

Save lszApprovalCode, lszSTAN, and szReferenceNumber (RRN) from Response.Transaction. Set lszSTAN to the last six characters of szReferenceNumber. Store these identifiers in your POS; Search Transaction uses the saved RRN and approval code (AuthId) to locate and confirm the matching record. Use PreAuthInquiry for Complete, Cancel, Increment, Extended, or Reversal, and PreAuthCompleteInquiry for Delayed. See Pre-auth Guide.

Request Example — Pre-auth

{
  "Merchant": "01",
  "TxnType": "PA",
  "Amount": 1500,
  "TxnRef": "123415890",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Pre-auth Complete TxnType: `AC`

The pre-auth complete transaction type allows the merchant to complete a pre-auth sale.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"AC"` (Pre-auth Complete).
Amount	long	M	Final charge amount in cents. Must be greater than 0.
RRN	string(12)	M	Original pre-auth retrieval reference. The last six characters are used as `lszSTAN`.
lszApprovalCode	string	M	Approval code from the original Pre-auth. Obtain via Search Transaction (`FuncType: "PreAuthInquiry"` with `RRN` and `AuthId`) or from the stored `PA` response.
lszSTAN	string	M	Last six characters of the original `RRN`.

Linking to the original pre-auth

Option 1: Search with FuncType: "PreAuthInquiry", RRN, and AuthId; select the returned record and use its szReferenceNumber (RRN), lszApprovalCode, and lszSTAN.
Option 2: Pass RRN, lszApprovalCode, and lszSTAN saved from the original PA response.

Request Example — Pre-auth Complete

{
  "Merchant": "01",
  "TxnType": "AC",
  "Amount": 100,
  "RRN": "123456789012",
  "lszApprovalCode": "328958",
  "lszSTAN": "000030",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Pre-auth Cancel TxnType: `PAC`

Cancels an open pre-auth. This transaction type is supported through the unattended POS Integration path only.

Also uses the common transaction response structure.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PAC"` (Pre-auth Cancel). Unattended mode only.
RRN	string(12)	M	Retrieval reference number from the original pre-auth.
lszApprovalCode	string	M	Approval code from the original pre-auth.
Amount	long	O	Not required by the current runtime for `PAC`.
lszSTAN	string	O	Not required by the current runtime for `PAC`.

Linking to the original pre-auth

Obtain RRN and lszApprovalCode from the original PA response or from Search Transaction using FuncType: "PreAuthInquiry".

Request Example — Pre-auth Cancel

{
  "Merchant": "01",
  "TxnType": "PAC",
  "RRN": "123456789012",
  "lszApprovalCode": "328958"
}

Pre-auth Increment TxnType: `PT`

The pre-auth increment transaction type enables the merchant to increase the amount of a pre-auth sale by adding a new amount to the previous pre-auth.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PT"` (Pre-auth Increment).
Amount	long	M	Additional amount in cents. Must be greater than 0.
RRN	string(12)	M	Original pre-auth retrieval reference. The last six characters are used as `lszSTAN`.
lszApprovalCode	string	M	Approval code from the original Pre-auth.
lszSTAN	string	M	Last six characters of the original `RRN`.

Linking to the original pre-auth

Option 1: Search with FuncType: "PreAuthInquiry", RRN, and AuthId; select the returned record and use its szReferenceNumber (RRN), lszApprovalCode, and lszSTAN.
Option 2: Pass RRN, lszApprovalCode, and lszSTAN saved from the original PA response.

Request Example — Pre-auth Increment

{
  "Merchant": "01",
  "TxnType": "PT",
  "Amount": 100,
  "RRN": "123456789012",
  "lszApprovalCode": "328958",
  "lszSTAN": "000030",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Pre-auth Delayed TxnType: `PD`

The pre-auth delayed transaction type is an optional message that may be sent when additional goods or services have been delivered after the final completion has been processed.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PD"` (Pre-auth Delayed).
Amount	long	M	Amount in cents. Must be greater than 0.
RRN	string(12)	M	Original pre-auth retrieval reference. The last six characters are used as `lszSTAN`.
lszApprovalCode	string	M	Approval code from the original Pre-auth Complete (`AC`).
lszSTAN	string	M	Last six characters of the original `RRN`.

Linking to the original pre-auth complete

Option 1: Search with FuncType: "PreAuthCompleteInquiry", RRN, and AuthId; select the returned completed pre-auth and use its szReferenceNumber (RRN), lszApprovalCode, and lszSTAN.
Option 2: Pass RRN, lszApprovalCode, and lszSTAN saved from the original AC response.

Unlike other follow-ups, Delayed references a completed pre-auth (AC), not the original authorization (PA).

Request Example — Pre-auth Delayed

{
  "Merchant": "01",
  "TxnType": "PD",
  "Amount": 100,
  "RRN": "123456789012",
  "lszApprovalCode": "328958",
  "lszSTAN": "000030",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Extended Pre-auth TxnType: `PE`

Extended Pre-auth extends a legacy pre-auth record. An amount is not required for PE. The original record is identified by lszApprovalCode and RRN.

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type	M/O	Description
TxnType	string(3)	M	Must be `"PE"`.
lszApprovalCode	string	M	Approval code from the original pre-auth.
RRN	string(12)	M	Retrieval reference number from the original pre-auth.
lszSTAN	string	M	Last six characters of the original `RRN`.

Linking to the original pre-auth

Option 1: Search with FuncType: "PreAuthInquiry", RRN, and AuthId; select the returned record and use its szReferenceNumber (RRN), lszApprovalCode, and lszSTAN.
Option 2: Pass RRN, lszApprovalCode, and lszSTAN saved from the original PA response.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/transaction

Request Example — Extended Pre-auth

{
  "Merchant": "01",
  "TxnType": "PE",
  "lszApprovalCode": "328958",
  "RRN": "123456789012",
  "lszSTAN": "789012",
  "AsyncMode": "0",
  "WithReceiptImageData": "1",
  "ReceiptType": 1
}

Pre-auth Reversal TxnType: `PR`

Pre-auth Reversal reverses an open pre-auth. Uses POST .../transaction with TxnType: "PR".

Also uses all common request fields. Response structure is defined in Transaction Response.

Type-Specific Request Fields

Field Name	Type (Max Length)	M/O	Description
TxnType	string(3)	M	Must be `"PR"` (Pre-auth Reversal).
Amount	long	M	Reversal amount in cents. Pass the amount for the reversal transaction.
RRN	string(12)	M	Retrieval reference number from the original Pre-auth.
lszApprovalCode	string	M	Approval code from the original Pre-auth (`PA`).
lszSTAN	string	M	Last six characters of the original `RRN`.

Linking to the original pre-auth

Option 1: Search with FuncType: "PreAuthInquiry", RRN, and AuthId; select the returned record and use its lszApprovalCode and szReferenceNumber (RRN).
Option 2: Pass values saved from the original PA response.

Request Example — Pre-auth Reversal

{
  "Merchant": "01",
  "TxnType": "PR",
  "Amount": 1500,
  "lszApprovalCode": "328958",
  "RRN": "123456789012",
  "lszSTAN": "789012",
  "AsyncMode": "0"
}

Search Transaction

Search Transaction has two inquiry modes and one local-search mode. PreAuthInquiry and PreAuthCompleteInquiry send the supplied identifiers to the payment gateway to find the source pre-auth record; Reprint searches matching print jobs stored on the terminal. See Pre-auth Guide for how search fits into the pre-auth flow.

FuncType is mandatory for every search. RRN and AuthId are mandatory only for PreAuthInquiry and PreAuthCompleteInquiry; they are optional or not used for Reprint as shown below.

Request Body Fields

Field Name	Type (Max Length)	M/O	Description
Merchant	string(2)	O	Specify the merchant to execute the transaction. See Table REQ-01.
FuncType	string(22)	M	Type of stored records to retrieve. Controls which follow-up operations the results support — see Table ENUM-11.
TxnRef	string	O	Optional transaction reference filter.
RRN	string(12)	M*	Required as the full retrieval reference for `PreAuthInquiry` and `PreAuthCompleteInquiry`; for `Reprint`, use the last six characters of the stored RRN as the optional local suffix filter.
TRV	string(15)	O	Optional gateway filter for `PreAuthInquiry` and `PreAuthCompleteInquiry`; not used for `Reprint`.
AuthId	string(6)	M*	Original transaction's `lszApprovalCode`. Required for `PreAuthInquiry` and `PreAuthCompleteInquiry`; omit for `Reprint`.
Stan	string(6)	O	Optional. Passed to the gateway for either pre-auth inquiry type; used as a database filter for `Reprint`.
Last4Digits	string(4)	O	Optional last-four-card-digits database filter for `Reprint`; not used for either pre-auth inquiry type.
AuthCode	string	O	Optional authorization-code filter.
Date	string	O	Accepted in the request model but not applied by the current POS Integration runtime; it does not filter search results.
Time	string	O	Accepted in the request model but not applied by the current POS Integration runtime; it does not filter search results.
Amount	long	O	Optional amount database filter in cents for `Reprint`; not used for either pre-auth inquiry type.
ExAmount	bool	O	Amount matching mode for the `Reprint` `Amount` filter; not used for either pre-auth inquiry type.
SearchAmount	long	O	Optional amount passed to the inquiry gateway, in cents; not used for `Reprint`.
IssuerRRN	string(15)	O	Optional issuer retrieval-reference gateway filter for either pre-auth inquiry type; not used for `Reprint`.

Field requirement by FuncType

Field	PreAuthInquiry	PreAuthCompleteInquiry	Reprint
FuncType	M	M	M
RRN	M	M	O
AuthId	M	M	Not used
Stan	O	O	O
TRV	O	O	Not used
IssuerRRN	O	O	Not used
SearchAmount	O	O	Not used
Amount	Not used	Not used	O
ExAmount	Not used	Not used	O
Last4Digits	Not used	Not used	O

Table ENUM-11 — FuncType field values

Enum table — colocated with Search Transaction. Also in Table Index.

Use FuncType to select the search purpose. For example, to find the original pre-auth before a Pre-auth Complete, set FuncType to "PreAuthInquiry" and send both RRN and AuthId. For Reprint, use the last six characters of the stored RRN. Date and Time are accepted request fields but are not applied by the current POS Integration runtime.

FuncType	Purpose
PreAuthInquiry	Find the original Pre-auth (`PA`) for Complete (`AC`), Cancel (`PAC`), Increment (`PT`), Reversal (`PR`), or Extended (`PE`).
PreAuthCompleteInquiry	Find the completed Pre-auth (`AC`) for Delayed (`PD`).
Reprint	Search matching print jobs stored on the terminal.

* Conditional mandatory field: both RRN and AuthId are M for PreAuthInquiry and PreAuthCompleteInquiry; for Reprint, RRN is O and AuthId is not used. Date and Time are accepted request fields but are not applied by the current POS Integration runtime.

Transaction Search Response

Search uses a separate transaction-detail item model. It is not the same required-field schema as Response.Transaction: fields may be omitted depending on the search mode and stored record. A normal transaction returns one object; search returns zero or more matching records in Response.Transactions[].

Single transaction vs search

Operation	ResponseType	Payload shape
Purchase, Pre-auth, etc.	`"transaction"`	`Response.Transaction` — one transaction object
Search Transaction	`"transactionsearch"`	`Response.Transactions` — array of transaction-detail items

Each element in Transactions[] is a matching stored transaction record. The transaction RRN is returned in szReferenceNumber when available. For a pre-auth follow-up, copy szReferenceNumber (RRN) and lszApprovalCode when present, then send lszSTAN as the last six characters of that RRN. See the search item fields and Transaction Response enum references.

Search-specific response envelope

Field Name	Type (Max Length)	M/O	Description
SessionId	string(36)	M	SessionId of the search request.
ResponseType	string(23)	M	Always `"transactionsearch"` (not `"transaction"`).
Transactions	array	M	Array of transaction-detail items. May contain 0, 1, or many records. Items use the fields returned for the selected search mode; absent fields must be treated as optional.

Do not require fields such as Merchant, TxnType, OrderID, or ResponseText on every search item. Enum values shared with transaction responses are in Transaction Response → Reference — Field Enums.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/transactionsearch

Request Example — look up a pre-auth for Complete, Cancel, Increment, Extended, or Reversal

{
  "Merchant": "01",
  "FuncType": "PreAuthInquiry",
  "RRN": "000001013731",
  "AuthId": "328408",
  "Stan": "013731",
  "SearchAmount": 1500,
  "IssuerRRN": ""
}

Response Example — matching pre-auth

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "transactionsearch",
  "Response": {
    "Transactions": [
      {
        "Merchant": "1",
        "TxnType": "PA",
        "Success": "1",
        "lAmount": 1500,
        "lAuthorizedTotal": 1500,
        "Date": "20240405",
        "Time": "22:19:22",
        "szReferenceNumber": "000001013731",
        "lszApprovalCode": "328408",
        "lszSTAN": "013731",
        "lszEndCardNumber": "2955",
        "PID": 8
      }
    ]
  }
}

Each object in Transactions[] uses the search transaction-detail model; fields may be omitted depending on the search mode and stored record. Use szReferenceNumber (RRN), lszApprovalCode, and lszSTAN when present in the follow-up request.

Reprint Receipt

Reprints the receipt of any approved transaction.

Uses the POST .../reprint endpoint. Use FuncType: "Reprint" in Search Transaction, then submit the last six characters of the selected transaction's szReferenceNumber as the reprint request RRN.

Reprint request fields

Field Name	Type (Max Length)	M/O	Description
Merchant	string(2)	O	Merchant to execute the reprint. See Table REQ-01.
RRN	string(12)	M	Last six characters of the stored retrieval reference number (RRN suffix), matched against the end of the stored RRN. Values shorter than six characters are rejected; the full RRN is also accepted. Native validation rejects an empty value.
WithReceiptImageData	bool	O	Requests supplementary receipt image/signature data when generated. Receipt content is controlled by `ReceiptType`.
ReceiptType	int	O	Receipt format. See Table REQ-02.
PlainTextCharPerLine	int	O	Plain-text receipt width.
DisablePrinting	bool	O	If enabled, disable physical receipt printing.
RunInBackground	bool	O	If enabled, run the reprint without displaying the transaction flow.

Reprint request note

The public contract uses RRN and the fields listed above. For this endpoint, the supported RRN input is the last six characters of the stored RRN; the suffix identifies the stored print job, and the most recent matching print job is used. The runtime may also accept legacy compatibility fields such as PID, Application, ReceiptAutoPrint, CutReceipt, ReprintType, OriginalTxnRef, Type, lszApprovalCode, and lszSTAN; these are not required by this contract.

Reprint response fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"reprint"`.
ResponseCode	string	O	Native response/result code when supplied by the print-job record.
Merchant	number	M	Merchant identifier.
Success	bool	M	Whether the operation succeeded.
ResponseText	string	O	Transaction result text returned by the original host when supplied. It describes the original transaction, not the reprint operation (for example `"APPROVED"`; code `08` may produce `"HONOUR WITH IDENTIFICATION"`).
ReceiptData	string	O	Receipt content when returned.
ReceiptLogo	string	O	Base64-encoded receipt logo when returned.
DigitalSig	string	O	Digital signature data when returned.
ReceiptType	int	M	Receipt format returned.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/reprint

Request Example

{
  "Merchant": "01",
  "RRN": "789012",
  "ReceiptType": 1,
  "WithReceiptImageData": true
}

Response Example (Success)

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "reprint",
  "Response": { "Merchant": 1, "Success": true, "ResponseText": "APPROVED", "ReceiptData": "...", "ReceiptType": 1 }
}

ResponseText is the original transaction result; it is not a reprint-status message.

Card Verification

Verifies the validity of a card without performing a financial transaction. The cardholder presents or inserts/taps their card; the terminal returns card details and authorization status.

Request Body Fields

Property	Type	M/O	Description
Merchant	string(2)	O	Specify the merchant to execute the transaction. See Table REQ-01.
ReceiptType	int	O	Receipt format. See Table REQ-02.
WithReceiptImageData	bool	O	Requests supplementary receipt image/signature data when generated. Receipt content is controlled by `ReceiptType`.
DisablePrinting	bool	O	If enabled, disable receipt printing.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"querycard"`.
Success	bool	M	Whether the transaction is approved (true) or declined (false).
ResponseText	string	M	Response description.
CardType	uint	O	Card type code.
CardName	string	O	Cardholder name.
AccountType	string(2)	O	Account type.
Pan	string(32)	O	Masked card number.
AuthCode	string(6)	O	Authorization code.
EntryMode	uint	O	Entry mode. See Table ENUM-04.
ReceiptData	string	O	Contains the receipt data of the transaction.
ReceiptLogo	string	O	Contains the logo to be printed on the receipt.
ReceiptType	int	M	Receipt format returned. See Table RES-01.
cardHash	string	O	Hash of the presented card number when the card is read successfully.

EntryMode values — see Table ENUM-04 under Transaction → Field Enums.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/querycard

Request Example

{
  "Merchant": "01",
  "ReceiptType": 1
}

Approved
Declined
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "querycard",
  "Response": {
    "ReceiptType": 1,
    "ReceiptData": "...",
    "Success": "1",
    "ResponseText": "APPROVED",
    "AccountType": "2",
    "Pan": "472674******8770",
    "CardType": 69,
    "EntryMode": 12,
    "AuthCode": "69074A",
    "cardHash": "a101cd4d84c5eca7ed4b1c9617d5d0ffda37049e7b6211d7e58b146cdac7e1b4"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "querycard",
  "Response": {
    "Success": "0",
    "ResponseText": "Declined",
    "ReceiptType": 1
  }
}

Card Enquiry

Reads the presented card and returns a card hash without performing a financial transaction. This operation is available through both the POS interface and unattended mode.

Request Body Fields

Property	Type	M/O	Description
Merchant	string(2)	O	Specify the merchant for the card enquiry. See Table REQ-01.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"cardenquiry"`.
ResponseText	string	M	Response description.
Success	bool	M	Whether the card enquiry succeeded.
cardHash	string	O	Hash of the presented card number when the card is read successfully.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/cardenquiry

Request Example

{
  "Merchant": "01"
}

Response Example

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "cardenquiry",
  "Response": {
    "Success": true,
    "ResponseText": "APPROVED",
    "cardHash": "..."
  }
}

Scan Code

Scans a QR code or barcode using the terminal scanner. This operation is available through both the POS interface and unattended mode.

Request Body Fields

Property	Type	M/O	Description
CodeType	string	O	Requested code format: `QrCode`, `Barcode`, or `AutoDetect` (case-insensitive). Omit or send empty for `AutoDetect`.
Timeout	int	O	Scanner timeout in seconds. Omit or send `0` to use the default of `60` seconds. Negative values are rejected as invalid request data.
FlashOn	bool	O	Whether to enable the scanner light.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"scancode"`.
Success	bool	M	Whether a code was scanned successfully.
ResponseText	string	O	Response description when supplied.
CodeType	string	M	Detected code format; defaults to `AutoDetect` when no type is returned by the scanner.
CodeValue	string	O	Scanned code value when successful.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/scancode

Request Example

{
  "CodeType": "QrCode",
  "Timeout": 30,
  "FlashOn": true
}

Response Example

{
  "SessionId": "{{sessionId}}",
  "ResponseType": "scancode",
  "Response": {
    "Success": true,
    "ResponseText": "Scan successful",
    "CodeType": "QrCode",
    "CodeValue": "..."
  }
}

Settlement Enquiry

Settlement Enquiry retrieves current settlement subtotals without performing a settlement cutover.

Settlement Enquiry and Settlement Cutover share the same POST .../settlement endpoint, request body, and response model. The operation is selected by SettlementType.

Enquiry vs Cutover

Operation	`SettlementType`	Request / response
Current settlement enquiry	`"E"`	Current settlement totals
Last-settlement enquiry	`"R"`	Last-settlement totals
Settlement Cutover	`"C"`	Batch cutover

Settlement request fields (shared)

Property	Type	M/O	Description
Merchant	string(2)	O	Specify the merchant to execute the transaction. See Table REQ-01.
SettlementType	string(1)	M	Enquiry: `"E"` = current enquiry, `"R"` = last-settlement enquiry. Cutover: `"C"`.
Application	string(2)	O	Application identifier.
ReceiptAutoPrint	string(1)	O	Receipt auto-print control.
CutReceipt	string(1)	O	Receipt cut control.
ResetTotals	string(1)	O	Reset totals control.
AccessCode	string(8)	O/M	Access code when settlement access-code management is enabled.
ReceiptType	int	O	Receipt format. See Table REQ-02.
WithReceiptImageData	bool	O	Requests supplementary receipt image/signature data when generated. Receipt content is controlled by `ReceiptType`.
PlainTextCharPerLine	int	O	Plain-text receipt width.
DisablePrinting	bool	O	Disable receipt printing.

SettlementType selects the current enquiry ("E"), last-settlement enquiry ("R"), or cutover ("C"). Nuvei does not support settlement enquiry by date.

Settlement response fields (shared)

Identical response structure for Enquiry and Cutover — ResponseType is always "settlement".

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"settlement"`.
ResponseCode	string	O	Native response/result code when supplied by the settlement record.
Success	bool	M	Whether the transaction is approved (true) or declined (false).
ResponseText	string	O	Text of response. Commonly occurs when a transaction is declined.
Merchant	number	M	Merchant identifier.
ReceiptType	int	O	Returned receipt format.
ReceiptData	string	O	Settlement receipt data.
ReceiptLogo	string	O	Receipt logo.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/settlement

Request Example

{
  "Merchant": "01",
  "SettlementType": "E",
  "ReceiptType": 1,
  "WithReceiptImageData": true,
  "DisablePrinting": false
}

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "settlement",
  "Response": {
    "Merchant": 1,
     "Success": true,
     "ReceiptType": 1,
     "ReceiptData": "..."
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "settlement",
  "Response": {
    "Merchant": 1,
     "Success": false,
     "ResponseText": "Transaction Cancelled",
     "ReceiptType": 1
  }
}

Settlement Cutover

Performs the end-of-day settlement cutover, closing the current batch and reconciling totals with the host.

Uses the same POST .../settlement endpoint and models as Settlement Enquiry. Set SettlementType to "C".

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/settlement

Request Example

{
  "Merchant": "01",
  "SettlementType": "C",
  "ReceiptType": 1,
  "WithReceiptImageData": true,
  "DisablePrinting": false
}

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "settlement",
  "Response": {
    "Merchant": 1,
    "Success": true,
    "ReceiptData": "...",
    "ReceiptType": 1
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "settlement",
  "Response": {
    "Merchant": 1,
    "Success": false,
    "ResponseText": "Cannot Complete",
    "ReceiptType": 1
  }
}

Manual Host Logon

Initiates a manual host logon. It can be used at the start of the business day or after a network issue. Transaction flows normally attempt host logon automatically when required; this endpoint remains available for an operator-initiated logon.

Request Body Fields

Property	Type	M/O	Description
Merchant	string(2)	O	Merchant identifier.
Application	string(2)	O	Application identifier.
ReceiptAutoPrint	string(1)	O	Receipt auto-print control.
CutReceipt	string(1)	O	Receipt cut control.
LogonType	string(2)	O	Logon operation type.
PurchaseAnalysisData	string	O	Purchase analysis data for the logon request.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"logon"`.
Success	bool	M	Whether the operation succeeded (true) or failed (false).
ResponseText	string	O	Error description on failure.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/logon

Request Example

{
  "Merchant": "01"
}

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "logon",
  "Response": {
    "Success": "1"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "logon",
  "Response": {
    "Success": "0",
    "ResponseText": "LOGON FAILED\nTRANSMISSION ERROR"
  }
}

Cancel Transaction

Requests cancellation of a transaction that is currently in progress on the terminal. The sessionId in the URL must match the sessionId of the transaction you want to cancel.

If the transaction has already passed the point of no return (e.g. processing at the host), the cancellation will be declined. If no active transaction is associated with the session, the terminal may still return HTTP 200 with Success: false, for example ResponseText: "Invalid Session ID".

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the transaction being canceled.
ResponseType	string	M	Always `"canceltransaction"`.
Success	bool	M	True = cancellation request accepted; false = cancellation declined.
ResponseText	string	M	Response description.

Endpoint

GET/POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/canceltransaction

No request body required

Cancellation accepted
Declined
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "canceltransaction",
  "Response": {
    "Success": "1",
    "ResponseText": "The transaction is being canceled"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "canceltransaction",
  "Response": {
    "Success": "0",
    "ResponseText": "Invalid Session ID"
  }
}

Query Transaction

Polls the current status of a transaction initiated in async mode. The sessionId in the URL must match the original transaction's sessionId.

When Status = 11 (WaitingForSignatureConfirmationFromClient) and DigitalSig is present in the response, call Approve Signature with the same sessionId — see Table ENUM-12.

If there is no transaction associated with the supplied session, the terminal can return HTTP 403 with an error envelope, such as ErrMessage: "no transactions found" or "Not allowed".

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the transaction.
ResponseType	string	M	Always `"querytransaction"`.
Status	int	M	Transaction status code. Possible values are listed in Table ENUM-12.
StatusText	string	O	Text of status of transaction when supplied. See Table ENUM-12.
TerminalID	string	O	Identifier of the payment terminal that is processing the transaction. Returned at the top level of `Response` when available.
IsCancelable	bool	O	Whether the current async flow can be canceled at this stage. Serialized as `"1"`/`"0"` or `true`/`false` according to TMS Boolean Type.
PrinterStatus	string	O	Printer state text returned by the terminal when available (for example out-of-paper / ready).
Transaction	object	O	Returned as an object when the status equals `1` (`TransactionCompleted`); read the gateway RRN from `Transaction.szReferenceNumber`. It can be `null` while the transaction is pending — see Table ENUM-12.

Endpoint

GET https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/querytransaction

No request body required

Completed
In Progress
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "querytransaction",
  "Response": {
    "Status": 1,
    "StatusText": "Transaction completed",
    "IsCancelable": "0",
    "TerminalID": "PX600821",
    "PrinterStatus": "Printer Ready",
    "Transaction": {
      "ReceiptType": 0,
      "PID": 5,
      "OrderID": "order-20260905-001",
      "Merchant": "1",
      "TxnType": "P",
      "Success": "1",
      "IdShift": 1,
      "IdShiftName": 0,
      "lAmount": 1000,
      "lTipAmount": 0,
      "lCashOut": 0,
      "lCashOutFee": 0,
      "lSurChargeTax": 0,
      "lDiscount": 0,
      "lDiscountPercent": 0,
      "iReward": 0,
      "lAuthorizedTotal": 1000,
      "lDonationAmount": 0,
      "iEntryMode": 7,
      "iCardType": 69,
      "iAccountType": 2,
      "iCurrencyCode": 36,
      "fsModify": 0,
      "iPaymentType": 0,
      "iCustomerLanguage": 1,
      "fClosed": 0,
      "fBatchError": 0,
      "fVoided": 0,
      "fRefunded": "0",
      "fAuthorized": "0",
      "fSignature": "0",
      "iCVVStatus": 0,
      "iMotoOrderType": 0,
      "fCanAdjust": "1",
      "fCanVoid": "1",
      "fCanPreAuthTopUp": "0",
      "fCanPreAuthComplete": "1",
      "fCanVoidPreAuthComplete": "0",
      "fCanGoOffline": "0",
      "lszCustomerReference": "1234567890",
      "Date": "20260905",
      "Time": "18:04:22",
      "szAuthorizationResponseCode": "00",
      "lszApprovalCode": "68549A",
      "szReferenceNumber": "000001007663",
      "lszSTAN": "007663",
      "lszEndCardNumber": "8770",
      "iReversalReason": 0,
      "szQRCode": "https://receipt.project-jump-start.com/example.html",
      "byPinType": 1,
      "byPinStatus": 3,
      "iNoCVVOption": 0,
      "byCDCVM": 0,
      "szMaskedCardNumber": "472674******8770",
      "cardHash": "a101cd4d84c5eca7ed4b1c9617d5d0ffda37049e7b6211d7e58b146cdac7e1b4"
    }
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "querytransaction",
  "Response": {
    "Status": 12,
    "StatusText": "Getting signature from customer",
    "IsCancelable": false,
    "TerminalID": "PX600821"
  }
}

Query Stored Transaction

Retrieves a previously stored transaction result from the terminal database. Optionally use OrderID in the request body to select an exact stored record. Use the same OrderID on the original request and the lookup request when an exact stored record is required.

On success, the response contains a full Transaction object — same field model as Transaction Response.

Request Body Fields

Field Name	Type (Max Length)	M/O	Description
OrderID	string(51)	O	Optional order identifier. The current native buffer reserves 52 bytes including the terminator, so 51 data characters are the safe maximum. When supplied, it identifies the stored transaction and should match the original transaction request. When omitted, the terminal may still return a stored transaction and the response may omit `OrderID`.
ReceiptType	int	O	Receipt format for returned receipt data. See Table REQ-02.
PlainTextCharPerLine	int	O	Plain-text receipt width when plain-text receipt output is requested.

Response

Same envelope as a financial transaction — Response.Transaction uses the field model in Transaction Response. The response type is "querytransaction". If no matching record exists, the terminal returns HTTP 400 with ErrMessage: "Transaction Not Found".

Not-found response

{"SessionId":"2174267867","ResponseType":"querytransaction","Response":{"ErrMessage":"Transaction Not Found","Suggestion":"","StatusCode":"400"}}

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/querystoredtransaction

Request Example

{
  "OrderID": "order-20260908-001",
  "ReceiptType": 1,
  "PlainTextCharPerLine": 32
}

Request Example — without OrderID

{
  "ReceiptType": 1,
  "PlainTextCharPerLine": 32
}

When OrderID is omitted, the terminal may still return a stored transaction and the response may omit OrderID. Include OrderID when an exact stored-record identifier is available.

Response Example — OrderID supplied

{
  "SessionId": "2174267867",
  "ResponseType": "querytransaction",
  "Response": {
    "Transaction": {
      "ReceiptType": 0,
      "PID": 3,
      "OrderID": "order-20260908-001",
      "Merchant": "1",
      "TxnType": "P",
      "Success": true,
      "IdShift": 1,
      "IdShiftName": 0,
      "lAmount": 21000,
      "lTipAmount": 0,
      "lCashOut": 0,
      "lCashOutFee": 0,
      "lSurChargeTax": 0,
      "lDiscount": 0,
      "lDiscountPercent": 0,
      "iReward": 0,
      "lAuthorizedTotal": 21000,
      "lDonationAmount": 0,
      "iEntryMode": 10,
      "iCardType": 70,
      "iAccountType": 2,
      "iCurrencyCode": 36,
      "fsModify": 0,
      "iPaymentType": 0,
      "iCustomerLanguage": 1,
      "fClosed": false,
      "fBatchError": false,
      "fVoided": false,
      "fRefunded": false,
      "fAuthorized": false,
      "fSignature": false,
      "iCVVStatus": 0,
      "iMotoOrderType": 0,
      "fCanAdjust": true,
      "fCanVoid": true,
      "fCanPreAuthTopUp": false,
      "fCanPreAuthComplete": true,
      "fCanVoidPreAuthComplete": false,
      "fCanGoOffline": false,
      "lszCustomerReference": "1234567890",
      "Date": "20260908",
      "Time": "13:09:58",
      "szAuthorizationResponseCode": "00",
      "lszApprovalCode": "656838",
      "szReferenceNumber": "000001014766",
      "lszSTAN": "014766",
      "lszEndCardNumber": "0708",
      "iReversalReason": 0,
      "szQRCode": "https://receipt.project-jump-start.com/PX60081220260809130958BwB9vgX.html",
      "byPinType": 1,
      "byPinStatus": 3,
      "iNoCVVOption": 0,
      "byCDCVM": 1,
      "szMaskedCardNumber": "550024******0708",
      "cardHash": "9b6d06dde0a15bf572587dccaed54f0b6023827a8a6b3410d7096f42af52a71f"
    }
  }
}

The successful stored-transaction example above uses JSON boolean mode (true). The completed Query Transaction example uses string mode ("1"); these examples are shown with different TMS Boolean Type representations. This is not an endpoint-specific difference: Success and other boolean fields follow the terminal's configured encoding across both endpoints. Clients must use and parse the encoding configured in TMS.

Approve Signature

This function lets the POS client submit the merchant's approve/reject decision for a signature-required transaction, provided that AsyncMode is enabled. Call this endpoint when querytransaction returns Status = 11 (WaitingForSignatureConfirmationFromClient) with a DigitalSig field — see Table ENUM-12.

Flow: POS submits transaction (AsyncMode enabled) → polls querytransaction → when Status=11 and DigitalSig present, call approvesignature (same sessionId) with Approval approve/reject → continue polling until Status=1.

Request Body Fields

Property	Type	M/O	Description
Approval	bool	M	True = approve the signature; false = reject the signature.

Response Fields

Property	Type	M/O	Description
SessionId	string(36)	M	SessionId of the request.
ResponseType	string	M	Always `"approvesignature"`.
Success	bool	M	True = updated; false = failed.
ResponseText	string(30)	O	Response description when supplied.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/approvesignature

Request Example

{
  "Approval": "1"
}

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "approvesignature",
  "Response": {
    "Success": "1",
    "ResponseText": "Update Successfully"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "approvesignature",
  "Response": {
    "Success": "0",
    "ResponseText": "Update Failed"
  }
}

Shift Totals

Returns the shift-total result.

Field	Type	M/O	Description
Merchant	string(2)	O	Merchant identifier.
IsStartNewShift	bool	O	Whether to start a new shift.
Success	bool	M	Whether the operation succeeded.
ResponseText	string	M	Operation result text.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/shiftTotals

Request Example — print current shift

{
  "Merchant": "01",
  "IsStartNewShift": false
}

Set IsStartNewShift to true to start a new shift.

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "shiftTotals",
  "Response": {
    "Success": true,
    "ResponseText": "Transaction Successful"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "shiftTotals",
  "Response": {
    "Success": false,
    "ResponseText": "Transaction Cancelled"
  }
}

Voucher Entry

Starts the voucher-entry operation.

Field	Type	M/O	Description
Merchant	string(2)	O	Merchant identifier.
ReceiptType	int	O	Receipt output mode. The POS client defaults to `2` (plain text).
PlainTextCharPerLine	int	O	Number of characters per line when plain-text receipt output is requested. The POS client default is `30`.
DisablePrinting	bool	O	Whether receipt printing is disabled.
Success	bool	M	Whether the operation succeeded.
ResponseText	string	M	Operation result text.
TransmissionDate	string	O	Transmission date when returned.
TransmissionTime	string	O	Transmission time when returned.
ReceiptData	string	O	Receipt data when returned.
ReceiptLogo	string	O	Receipt logo when returned.
DigitalSig	string	O	Digital signature when returned.

Endpoint

POST https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/voucherEntry

Request Example

{
  "Merchant": "01",
  "ReceiptType": 2,
  "PlainTextCharPerLine": 30,
  "DisablePrinting": false
}

Success
Failed
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "voucherEntry",
  "Response": {
    "Success": "1",
    "ResponseText": "No Offline Trans To Upload",
    "TransmissionDate": "20260907",
    "TransmissionTime": "18:06:51"
  }
}
{
  "SessionId": "{{sessionId}}",
  "ResponseType": "voucherEntry",
  "Response": {
    "Success": false,
    "ResponseText": "Upload Failed",
    "TransmissionDate": "20240806",
    "TransmissionTime": "09:30:00"
  }
}

Device mode

Device-mode indicates whether the client and payment app run on the same device.

Value	Description
on	Same device
off	Separate devices

The device-mode query parameter is optional and applies to all API endpoints that end with /transaction. If you don't include it in the request URL, the system assumes device-mode=off by default, meaning the client and the payment app run on separate devices.

Device-mode API request

A device-mode request looks like this.

https://{{pos-server}}:{{pos-port}}/v1/sessions/{{sessionId}}/transaction?device-mode=on

Reference Table Index

All lookup tables use a consistent ID format — not the legacy Word section numbers. Prefix indicates the table group; the number is sequential within that group.

REQ-## — request field logic (under Transaction → Request field logic)
RES-## — response field logic (under Transaction → Response field logic)
ENUM-## — field enum values (named constants / allowed values for a field). Most live under Transaction → Field Enums; some are colocated with the API that uses them (e.g. Mode on Get Merchant List).

Placement rule: REQ / RES tables and the main ENUM set live under Transaction. ENUM tables for a single endpoint may sit next to that endpoint — the ENUM prefix still applies because the content is a value list.

Transaction — request field logic

Table	Title	Used by
REQ-01	Merchant field logic	`Merchant` on transaction and other requests
REQ-02	ReceiptType field logic (request)	`ReceiptType` request field
REQ-03	Print Option	`CustomerReceiptPrintOption`, `MerchantReceiptPrintOption`

Transaction — response field logic

Table	Title	Used by
RES-01	ReceiptType field logic (response)	`ReceiptType` in transaction/search responses

Transaction — field enums

Table	Title	Field
ENUM-01	`fsModify` field values	`fsModify`
ENUM-02	`iAccountType` field values	`iAccountType`
ENUM-03	`iCardType` field values	`iCardType`
ENUM-04	`EntryMode` / `iEntryMode` field values	`iEntryMode`, Card Verification `EntryMode`
ENUM-05	`iPaymentType` field values	`iPaymentType`
ENUM-06	`iCustomerLanguage` field values	`iCustomerLanguage`
ENUM-07	`iReversalReason` field values	`iReversalReason`
ENUM-08	`byPinType` field values	`byPinType`
ENUM-09	`byPinStatus` field values	`byPinStatus`
ENUM-10	`Mode` field values	Get Merchant List → `Mode`
ENUM-11	`FuncType` field values	Search Transaction → `FuncType`
ENUM-12	`Status` and `StatusText` field values	Sync vs Async, Query Transaction

Changelog

Version history for the POS Integration API specification.

QA_1.3.342026/10/27by Huy Nguyen

CHANGEDPrint the merchant signature copy when a paper signature is required, even if DisablePrinting is enabled.CHANGEDAsk for the MOTO password before manual card entry on the terminal when the MOTO password is enabled.CHANGEDReject a transaction type disabled for the merchant, and manual card entry when MOTO is disabled, with "This Feature Is Not Available".CHANGEDAn omitted CustomerReceiptPrintOption or MerchantReceiptPrintOption follows the terminal receipt configuration.

QA_1.3.302026/09/29by Huy Nguyen

CHANGEDAdd optional TerminalID to querytransaction responses, including completed and pending signature-status responses.

QA_1.3.292026/09/08by Lien Le

CHANGEDUpdate the specification to QA_1.3.29 and align transaction RRN, response, search, and reprint guidance.

QA_1.3.262026/08/22by Lien Le

NEWAdd Card Enquiry (cardenquiry) and Scan Code (scancode) endpoints for POS interface and unattended mode, with their request and response fields.NEWAdd unattended-only Pre-auth Cancel (PAC) with original RRN and approval-code linking.CHANGEDAdd IsMaxAmount to Pre-auth; the flag uses the maximum amount configured in MaxStore for unattended mode.CHANGEDAdd RunInBackground to Reprint.

QA_1.3.252026/08/07by Lien Le

CHANGEDAlign the API reference with the request/response fields, receipt controls, and logon request.CHANGEDAlign user-facing function names, including Pre-auth Increment, Refund Amount, Cash Only, Card Verification, and Query Stored Transaction.REMOVEDRemove the pre-auth-specific reprint entry; retain Reprint Receipt only.CHANGEDDocument native Search Transaction filters: TxnRef, AuthCode, Date, and Time.

QA_1.3.242026/07/23by Lien Le

NEWPort the legacy POS Integration endpoint and field reference.

On-Premise Integration

Introduction

Sync vs Async Mode

Summary

Summary

API Requests

API Responses

HTTP status

Business fields (HTTP 200)

1. Success (HTTP 200)

2. Business failure (HTTP 200)

3. Error / exception (HTTP 400 / 401 / 403)

Quick reference

Boolean Type

Build a Server Validation Handler

Get Merchant List

Get Allowed Transactions

Health Check

Bring App to Foreground

Transaction

Common Request Fields

EnableTip behavior

Disabled functions and manual card entry

Reference — Request field logic

Transaction Response

Reference — Response field logic

Reference — Field Enums

Purchase TxnType: P

Refund Amount TxnType: R

Cash Only TxnType: C

Purchase Cash TxnType: PC

MOTO Purchase TxnType: MP

MOTO Refund TxnType: MR

Pre-auth Family — Developer Guide

Linking follow-up requests

Search Transaction ↔ Pre-auth

Pre-auth TxnType: PA

After approval

Pre-auth Complete TxnType: AC

Linking to the original pre-auth

Pre-auth Cancel TxnType: PAC

Linking to the original pre-auth

Pre-auth Increment TxnType: PT

Linking to the original pre-auth

Pre-auth Delayed TxnType: PD

Linking to the original pre-auth complete

Extended Pre-auth TxnType: PE

Linking to the original pre-auth

Pre-auth Reversal TxnType: PR

Linking to the original pre-auth

Search Transaction

Single transaction vs search

Reprint Receipt

Reprint request note

Card Verification

Card Enquiry

Scan Code

Settlement Enquiry

Enquiry vs Cutover

Settlement Cutover

Manual Host Logon

Cancel Transaction

Query Transaction

Query Stored Transaction

Approve Signature

Shift Totals

Voucher Entry

Device mode

Reference Table Index

Changelog

Purchase TxnType: `P`

Refund Amount TxnType: `R`

Cash Only TxnType: `C`

Purchase Cash TxnType: `PC`

MOTO Purchase TxnType: `MP`

MOTO Refund TxnType: `MR`

Pre-auth TxnType: `PA`

Pre-auth Complete TxnType: `AC`

Pre-auth Cancel TxnType: `PAC`

Pre-auth Increment TxnType: `PT`

Pre-auth Delayed TxnType: `PD`

Extended Pre-auth TxnType: `PE`

Pre-auth Reversal TxnType: `PR`