# 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](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-configuration-and-connectivity\&section=qhv6nzspm4fa7zajc43yr3ka). You also need the RSA key pair generated and the DUKPT keys injected — see [Generate and Inject Encryption Keys](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-generate-and-inject-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:

| Field | Attribute | Description |
| --- | --- | --- |
| **[CID]** | 3 ANS | Command Identifier: **“Y19”**. |
| **[RSA]** | 256..512 ANS | Public RSA Modulus for encrypting sensitive tracks. |
| **[EXP]** | 1..12 ANS | RSA Public Exponent. |
| **[TEC]** | 3 N | Command timeout in seconds ("000" to "999"). |
| **[PMK]** | 1 AN | MK position (Slot 3 for DUKPT); use "N" if no PIN is requested. |
| **[WRK]** | 1..16 ANS | WorkingKey status; use "N" if not applicable. |
| **[IMP]** | 12 N | **Transaction Amount**: 12-digit numeric (e.g., \$1.99 = `000000000199`). |
| **[ICB]** | 12 N | **Cashback Amount**: 12-digit numeric (set to `0` if not used). |
| **[TTY]** | 2 N | **Transaction Type**: `00` for Purchase, `20` for Refund. |

> **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]

| Field | Attribute | Description |
| --- | --- | --- |
| **[CID]** | 3 ANS | Command Identifier: **“Y19”**. |
| **[TJA]** | 1..19 N | Masked PAN (e.g., `52874560****4005`). |
| **[MDI]** | 1 A | Mode of Entry: **"L"** (Contactless). |
| **[TC2]** | 256..512 ANS | RSA-Encrypted Track II data. |
| **[CPG]** | 1..300 ANS | EMV Cryptogram (ARQC/TC) for authorization. |
| **[APN]** | 0..32 ANS | Application Name (e.g., "VISA CLASSIC"). |
| **[AID]** | 0..16 ANS | Selected Application Identifier (AID). |
| **[PIN]** | 16..32 ANS | DUKPT-Encrypted PINblock (if applicable). |
| **[KSN]** | 20 N | Key Serial Number for PIN decryption. |

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

**Host System Request (Y19):**

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

```

**Pinpad Response (Contactless Success):**

```text
<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]

| Field | Attribute | Description |
| --- | --- | --- |
| **[CID]** | 3 ANS | Command Identifier: **“Y19”**. |
| **[TJA]** | 1..19 N | Masked PAN. |
| **[CSE]** | 3 N | Service Code from Track II. |
| **[NYA]** | 1..26 ANS | Cardholder Name (if available). |
| **[MDI]** | 1 A | Mode: **"C"** (Chip) or **"B"** (Banda). |

### 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.

```kotlin
/**
 * 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.

```kotlin
/**
 * 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.

```kotlin
/**
 * 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:

| Operation | 1st Command | 2nd Command | 3rd Command | 4th Command |
| --- | --- | --- | --- | --- |
| **Contactless** | **Y19** (Final) | — | — | — |
| **Chip** | **Y19** (Init) | **Y15** (Optional) | **Y02** (Data) | **Y03** (Auth) |
| **Banda** | **Y19** (Init) | **Y02** (Data) | — | — |

## Next steps

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

1. [**Cashback Operations**](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-process-cashback-operations&section=kei2fli2gqggbwgaddtl3xb7): Learn how to configure purchase transactions that include cash withdrawal.
2. [**Cancellations and Refunds**](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-cancellations-and-refunds&section=kei2fli2gqggbwgaddtl3xb7): Learn how to stop an active command or process a transaction refund.
3. [**Error Handling**](https://docs.globalgetnet.com/en/products/in-store-payments/host-to-host?doc=h2h-error-handling&section=kei2fli2gqggbwgaddtl3xb7): Understand how to interpret Y0E report codes when a transaction fails.