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. También necesita el par de claves RSA generado y las claves DUKPT inyectadas. Consulte Genere e inyecte las claves de cifrado, 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:

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]

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

Solicitud del Sistema Host (Y19):

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

Respuesta del Pinpad (éxito contactless):

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

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.

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

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

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

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: aprenda a configurar transacciones de compra que incluyan retiro de efectivo.
2. Cancelaciones y Devoluciones: aprenda a detener un comando activo o a procesar la devolución de una transacción.
3. Manejo de Errores: comprenda cómo interpretar los códigos de reporte Y0E cuando falla una transacción.