Skip to main content

Documentation Index

Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt

Use this file to discover all available pages before exploring further.

The cardDetect method activates the terminal’s reader to identify and capture data from a payment method (Card or QR) without initiating a financial hold or charge. It serves as a versatile tool for workflows where customer identification must precede the payment phase. Use this method to:
  • Recognize customers via loyalty cards or mobile QR codes to apply personalized discounts.
  • Retrieve masked card data to welcome returning users or verify membership status.
  • Use card data to determine eligible fuel types or promotions before requesting authorization.
  • Accept Contactless (CTLS), Chip (EMV), Magnetic Stripe (Swipe), and QR code scanning.
Example of the card detection prompt on a Nayax device: cardDetect

​
Requests

All requests must include the command and a unique requestId. While this method does not authorize funds, an amount must be provided for display purposes on the terminal screen. The following example shows a typical request: 
{
"command": "cardDetect",
"requestId": "req-005",
"data": {
"amount": 50000,
"tranType": 1,
"channels": ["CTLS", "CHIP", "SWIPE"]
}
}

​
Parameter Definitions

The table below describes the parameters available for the detection request:
NameTypeRequiredDescription
amountintegerYesThe amount to display on the screen during detection (refer to decimalPlace).
tranTypeintegerNo1: Pre-authorization, 2: Pre-selection (Default is 1).
channelsarrayNoDefines allowed payment methods: CTLS, CHIP, SWIPE, or QR. Defaults to all if omitted.
buttonMediaIdstringNoOptional button displayed below the channels image. Currently supported value: useQR.

​
Responses

The VPOS terminal returns a response once the user interacts with the reader or a QR code is successfully scanned. The following example shows a typical credit card response: 
{
"requestId": "req-005",
"data": {
"state": "CARD_READ",
"cardBrand": "VISA",
"cardEntryMode": "CTLS",
"maskedPan": "************1234",
"aid": "A0000000031010"
}
}
The following example shows a typical QR code response: 
{
"requestId": "req-005",
"data": {
"state": "CARD_READ",
"cardEntryMode": "QR",
"qrCode": "1168743871706458"
}
}
The following example shows a button press response: 
{
"requestId": "req-005",
"data": {
"state": "BUTTON_PRESS"
}
}
Note: When using cardDetect for non-credit card methods (such as proprietary QR codes) or when a button is pressed, the client system is responsible for any subsequent authorization or settlement logic. The reader is automatically disabled after a QR code scan or button press.

​
Response Parameters

The response data is categorized by the entry mode used by the customer:
NameTypeDescription
statestringCARD_READ upon a successful card or QR detection; BUTTON_PRESS when the optional button is pressed.
cardEntryModestringThe method used to capture the data: CTLS, CHIP, SWIPE, or QR. Not present for BUTTON_PRESS.
cardBrandstringThe brand of the detected card (e.g., VISA, MASTERCARD).
maskedPanstringThe masked Primary Account Number for identification purposes.
aidstringThe Application Identifier for EMV-based transactions.
qrCodestringThe raw data string captured from a scanned QR code.