# Procesar pagos con tarjeta

Esta guía ofrece un recorrido técnico detallado para implementar los flujos de pago con tarjeta —Contactless, Chip y Banda Magnética— con la solución Pinpad Getnet.

## Cómo funciona

La integración sigue dos rutas secuenciales principales según la tecnología detectada al presentar la tarjeta:

1. **Flujo simplificado (Contactless):** la transacción se completa en un único intercambio de comandos (**Y19**).
2. **Flujo secuencial (chip y banda magnética):** requiere una serie de intercambios de comandos (**Y19, Y02, Y03**) para capturar datos sensibles y procesar las respuestas del emisor.

## Antes de comenzar

El terminal debe estar conectado y responder a la prueba de eco `Y0I`, como se describe en [Configuración y Conectividad](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-configuration-and-connectivity\&section=qhv6nzspm4fa7zajc43yr3ka). También necesita el par de claves RSA generado y las claves DUKPT inyectadas. Consulte [Genere e inyecte las claves de cifrado](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-generate-and-inject-keys), porque `Y19` transporta el módulo y el exponente RSA.

## Paso 1: Inicialice la transacción

El Sistema Host usa el comando **Y19** para "despertar" al Pinpad y solicitar la entrada de la tarjeta. Contiene la información mínima necesaria para iniciar una transacción, incluidos los importes y las claves de cifrado.

### Payload de solicitud Y19 [Host]

La siguiente tabla define los campos obligatorios del requerimiento Y19:

| Campo | Atributo | Descripción |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador de comando: **“Y19”**. |
| **[RSA]** | 256..512 ANS | Módulo RSA público para cifrar las pistas sensibles. |
| **[EXP]** | 1..12 ANS | Exponente público RSA. |
| **[TEC]** | 3 N | Tiempo de espera del comando en segundos ("000" a "999"). |
| **[PMK]** | 1 AN | Posición de la MK (Ranura 3 para DUKPT); use "N" si no se solicita PIN. |
| **[WRK]** | 1..16 ANS | Estado de la WorkingKey; use "N" si no aplica. |
| **[IMP]** | 12 N | **Importe de la transacción**: numérico de 12 dígitos (ej., \$1.99 = `000000000199`). |
| **[ICB]** | 12 N | **Importe del cashback**: numérico de 12 dígitos (establézcalo en `0` si no se usa). |
| **[TTY]** | 2 N | **Tipo de transacción**: `00` para compra, `20` para devolución. |

> **Descriptor de facturación:** para todas las operaciones Host-to-Host, el campo `billing_descriptor` de la API debe permanecer vacío.

### Comportamiento del terminal e interfaz de usuario

Una vez validado el requerimiento Y19, el terminal pasa a la pantalla de presentación de la tarjeta.

Como se muestra en la lógica de implementación anterior, el terminal actualiza su estado interno a `WAITING_CARD` y muestra el `request_card_msg` configurado.

## Paso 2: Implemente el flujo contactless (CTLSS)

En las transacciones Contactless (NFC), el proceso es más directo. El terminal ejecuta los pasos EMV de forma automática y devuelve una respuesta final con todos los datos de autorización necesarios. El flujo del Pinpad termina de inmediato después de esa respuesta.

### Respuesta Y19 - modo contactless [Pinpad]

| Campo | Atributo | Descripción |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador de comando: **“Y19”**. |
| **[TJA]** | 1..19 N | PAN enmascarado (ej., `52874560****4005`). |
| **[MDI]** | 1 A | Modo de entrada: **"L"** (Contactless). |
| **[TC2]** | 256..512 ANS | Datos de la Pista II cifrados con RSA. |
| **[CPG]** | 1..300 ANS | Criptograma EMV (ARQC/TC) para la autorización. |
| **[APN]** | 0..32 ANS | Nombre de la aplicación (ej., "VISA CLASSIC"). |
| **[AID]** | 0..16 ANS | Identificador de aplicación (AID) seleccionado. |
| **[PIN]** | 16..32 ANS | PINblock cifrado con DUKPT (si aplica). |
| **[KSN]** | 20 N | Número de serie de clave para descifrar el PIN. |

Este ejemplo muestra la comunicación serie directa de una transacción Visa Contactless exitosa.

**Solicitud del Sistema Host (Y19):**

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

```

**Respuesta del Pinpad (éxito contactless):**

```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}

```

## Paso 3: Implemente el flujo de chip y banda magnética

Si se inserta una tarjeta (**CHIP**) o se desliza (**BANDA**), el terminal devuelve una respuesta Y19 intermedia y espera nuevas instrucciones mediante el comando **Y02**.

> **Planes de cuotas:** si un plan identifica las cuotas con un modelo específico (ej., 11 cuotas que representan un "Plan Emisor 6 cuotas"), el Sistema Host debe convertir esos valores antes de enviar la solicitud a Getnet.

### Respuesta Y19 - modo BANDA/CHIP [Pinpad]

| Campo | Atributo | Descripción |
| --- | --- | --- |
| **[CID]** | 3 ANS | Identificador de comando: **“Y19”**. |
| **[TJA]** | 1..19 N | PAN enmascarado. |
| **[CSE]** | 3 N | Código de servicio de la Pista II. |
| **[NYA]** | 1..26 ANS | Nombre del titular de la tarjeta (si está disponible). |
| **[MDI]** | 1 A | Modo: **"C"** (Chip) o **"B"** (Banda). |

### Comandos posteriores

1. **Solicitud de datos adicionales (Y02):** el Sistema Host lo envía para activar el teclado seguro de introducción del PIN o para recuperar las pistas cifradas.
2. **Procesar la respuesta del emisor (Y03 - solo chip):** después de la autorización en línea, envíe la respuesta del emisor (código de autorización, código de respuesta y scripts del emisor) al Pinpad para ejecutar el "Second Generate AC".

## Referencia de implementación

Para que su equipo de desarrollo comprenda la máquina de estados interna del terminal, esta es la lógica funcional que usa el Pinpad durante una transacción.

### CommandY19: definición de clase

Esta clase representa el comando de inicialización que se usa en transacciones contactless, con chip o de banda magnética.

```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: punto de entrada de la transacción

Esta función privada es el controlador principal de la lógica del comando `Y19`.

```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?)

```

### Gestión del estado de la UI: setWaitingCardUIState

Cuando el Pinpad recibe un `Y19` válido, debe pasar la interfaz de usuario a un estado de "espera". La siguiente lógica ilustra cómo el terminal gestiona la visualización de los importes y los avisos de cashback.

```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)
}

```

## Secuencia de comandos por tecnología

La siguiente tabla compara el orden de los comandos frente a la tecnología:

| Operación | 1.er comando | 2.º comando | 3.er comando | 4.º comando |
| --- | --- | --- | --- | --- |
| **Contactless** | **Y19** (final) | — | — | — |
| **Chip** | **Y19** (inicio) | **Y15** (opcional) | **Y02** (datos) | **Y03** (autorización) |
| **Banda** | **Y19** (inicio) | **Y02** (datos) | — | — |

## Siguientes pasos

Después de implementar los flujos de pago, asegúrese de que su sistema gestione los escenarios operativos y los errores:

1. [**Operaciones de Cashback**](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-process-cashback-operations&section=kei2fli2gqggbwgaddtl3xb7): aprenda a configurar transacciones de compra que incluyan retiro de efectivo.
2. [**Cancelaciones y Devoluciones**](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-cancellations-and-refunds&section=kei2fli2gqggbwgaddtl3xb7): aprenda a detener un comando activo o a procesar la devolución de una transacción.
3. [**Manejo de Errores**](https://docs.globalgetnet.com/es/products/in-store-payments/host-to-host?doc=h2h-error-handling&section=kei2fli2gqggbwgaddtl3xb7): comprenda cómo interpretar los códigos de reporte `Y0E` cuando falla una transacción.