Process Card Payments

This guide provides a detailed technical walkthrough for implementing card payment flows—Contactless, Chip, and Magnetic Stripe—using the Pinpad Getnet solution.

How it works

The integration follows two primary sequential paths depending on the technology detected during card presentment:

1. Simplified Flow (Contactless): The transaction is completed within a single command exchange (Y19).
2. Sequential Flow (Chip & Magnetic Stripe): Requires a series of command exchanges (Y19, Y02, Y03) to capture sensitive data and process issuer responses.

Before you begin

The terminal must be connected and answering the Y0I echo test, as described in Configuration and Connectivity. You also need the RSA key pair generated and the DUKPT keys injected — see Generate and Inject Encryption Keys — because Y19 carries the RSA modulus and exponent.

Step 1: Initialize the transaction

The Y19 command is used by the Host System to “wake up” the Pinpad and request card entry. It contains the minimum information required to begin a transaction, including amounts and encryption keys.

Y19 request payload [Host]

The following table defines the mandatory fields for the Y19 requirement:

Billing Descriptor: For all Host-to-Host operations, the billing_descriptor field in the API must remain empty.

Terminal behavior and UI

Once the Y19 requirement is validated, the terminal transitions to the card presentment screen.

As shown in the implementation logic above, the terminal updates its internal state to WAITING_CARD and displays the configured request_card_msg.

Step 2: Implement the contactless flow (CTLSS)

For Contactless (NFC) transactions, the process is streamlined. The terminal executes EMV steps automatically and returns a final response containing all necessary authorization data. The flow for the Pinpad ends immediately after this response.

Y19 response - contactless mode [Pinpad]

This example demonstrates the raw serial communication for a successful Visa Contactless transaction.

Host System Request (Y19):

<STX>Y199BAE56E243A19FA882F7499824DAF558BA710B749E57E60AFF69FF5562C444C08144D2B5E361731AE06D9D1C43E7B6D0E401D04867CC470B524767838843DEB40330CA99D20F99DB6E5B882C696976C522A15855A9BBB5D156BE6BC49CA40759B37ECD57580BD7B6CB473CC2B95DA4558DCB1850D0693AD216BC7B9954B86AEC0FC45CFB954D0F1587C215FCE57FEC91B544DA17C2E9633F0EFA3A262AAB7D7A05D85F9D3753A94CD281DB6766EDB0D61FE8781773A4228215932D49F522E829622A519E6DEFC80C3A2B967AFDCEE77F69302DC90044FD39D99FBE80CB245A768160FA38A80A32D42B86361514E02685387B096A4D0B92D57EE024C38E26BEFF<FS>10001<FS>10500100000000000000000000000412399000000000000001<ETX>{LRC}

Pinpad Response (Contactless Success):

<ACK><STX>Y1945079900****1026<FS>201000PAYWAVE/VISA<FS>000041L1.9.7.1-dev<FS>250350780fca98e5d7768aa626e040ab60b019e57ec812b6127b48144ffa430274a6e6784db873bc758eb73fcc278241f5fcef095303b266a41005984c686f228f23685964e5c2737352e86e275d43c2922d4029f1986513d724021673b7d20e56a4bafb5fc7fad3210b095dc6df243a8f24b8d53dce5ca1285c0d928bb7ef067e0e0840cef0d2cd22040b1e70269a320958dc7e0a2d8d7a74bca2e12c9d4ac53502a604f990640479d9a65095de5a38f907219dcccba49d9104a10828b425d692f6b28bcf42130dc0d24bfb7dc1931c86748dfd65db0557af796b9b6f72fefd01583c8e0e729f04794fdcb91a4066ee7ae8278f015146af286768a80e089dd09343<FS>1NDB900008014<FS>9f370466f228639f36020475950500000000009a032505069c01009f02060000004123999f0306000000000000820220009f3303e0f8c89f1e0838353130494343008407a00000000310109f1a0200325f2a0200325f3401009f2701809f260874bbfcfa90874f229f100706010a03a02808<FS>000005649534120434C4153534943<FS>A0000000031010<FS>N<ETX>{LRC}

Step 3: Implement the chip and magnetic stripe flow

If a card is inserted (CHIP) or swiped (BANDA), the terminal returns an intermediate Y19 response and waits for further instructions via the Y02 command.

Installment Plans (Cuotas): If a plan identifies installments using a specific model (e.g., 11 installments representing a “Plan Emisor 6 installments”), the Host System must convert these values before sending the request to Getnet.

Y19 response - BANDA/CHIP mode [Pinpad]

Subsequent commands

1. Request Additional Data (Y02): The Host System sends this to trigger the secure keyboard for PIN entry or to retrieve encrypted tracks.
2. Process Issuer Response (Y03 - Chip Only): After online authorization, send the issuer response (Auth Code, Response Code, and Issuer Scripts) back to the Pinpad to perform the “Second Generate AC”.

Implementation reference

To help your development team understand the terminal’s internal state machine, here is the functional logic used by the Pinpad during a transaction.

CommandY19: class definition

This class represents the initialization command used in contactless, chip, or magnetic stripe transactions.

/**
 * This class represents the Y19 command used in contactless, contact chip, or magnetic stripe transactions.
 * * The Y19 command serves multiple purposes:
 * - It wakes up the payment processor (PP) and requests the user to insert the card.
 * - It returns relevant information to the cashier, including the card number (masking the middle part),
 * the Service Code, and the Bank Code.
 * - It sends the base amount and cashback amount, enabling EMV CTLSS reading without a second card tap.
 * - For chip or magnetic stripe, the flow continues with predefined commands (Y02).
 */
class CommandY19(rawCmd: String?) : Command()

handleCommandY19: transaction entry point

This private function serves as the primary handler for the Y19 command logic.

/**
 * Handles the Y19 command, "Init transaction".
 * This function:
 * - Implements a state machine to handle the Y19 command.
 * - Is the entry point for all EMV or magnetic stripe transactions.
 * - Requests the card entry.
 * - If CTLSS, the message is responded to and the transaction is completed.
 * - If magnetic stripe or EMV Contact, the terminal waits for the Y02 command.
 */
private fun handleCommandY19(inCmd: String?)

UI state management: setWaitingCardUIState

When the Pinpad receives a valid Y19, it must transition the UI to a “waiting” state. The following logic illustrates how the terminal handles the display of amounts and cashback prompts.

/**
 * Updates the UI state to indicate that the system is waiting for a card to be presented.
 */
fun setWaitingCardUIState(
    currencySymbol: String,
    amount: String,
    isCashback: Boolean = false,
    cashbackAmount: String = "",
    totalAmount: String = ""
) {
    Log.d(TAG, "setWaitingCardUIState")
    viewModel._state.value = viewModel._state.value.copy(
        messageTitle = viewModel.context.getString(R.string.request_card_msg),
        messageAmount = currencySymbol + amount,
        transactionState = TransactionState.WAITING_CARD,
    )
    
    if (isCashback) {
        setIsCashbackState(true)
        viewModel._state.value = viewModel._state.value.copy(
            cashbackAmount = currencySymbol + cashbackAmount,
            totalAmount = currencySymbol + totalAmount
        )
    }
    // Prevent the screen from sleeping during card entry
    DeviceHandler.setScreenOffTimeout(SCREEN_TIMEOUT_NO_SLEEP)
}

Command sequence by technology

The following table shows a comparison considering the command order vs. technology:

Next steps

After implementing the payment flows, ensure your system handles operational scenarios and errors:

1. Cashback Operations: Learn how to configure purchase transactions that include cash withdrawal.
2. Cancellations and Refunds: Learn how to stop an active command or process a transaction refund.
3. Error Handling: Understand how to interpret Y0E report codes when a transaction fails.