Crear un pago Tarjeta Presente de un solo paso

Esta guía le orientará en el procesamiento de una transacción de pago completa de un solo paso utilizando la Getnet Regional API para entornos Tarjeta Presente. Este flujo consiste en la captura de datos de pago directamente desde el hardware físico sin una autorización previa.

Requisitos

Antes de seguir los pasos, debe:

Credenciales: Obtenga su client_id y client_secret a través del equipo de Soporte a la Integración.
Autenticación: Genere un Bearer token a través del punto de enlace de Autenticación.
Identificación del hardware: Disponga de un terminal_number válido registrado para su dispositivo físico.

Especificaciones del caso de uso: Métodos de verificación de tarjeta

Las transacciones Tarjeta Presente requieren un Método de Verificación del Titular (CVM) y un Modo de Entrada (Entry Mode) definidos en el objeto card.

Chip + PIN: Requiere que el hardware capture un pin_block cifrado y un ksn (Key Serial Number).
Chip (Sin CVM): Se utiliza para transacciones de bajo valor o pagos sin contacto que no requieren PIN.
Banda magnética: La tarjeta se desliza por el lector y se transmiten los datos completos de track_2.

Proceso Tarjeta Presente de un solo paso

Para los flujos de un solo paso, establezca el payment_method en DIRECT_CREDIT o DIRECT_DEBIT para asegurar la captura inmediata.

Paso 1: Capturar el pago

Para procesar un pago de un solo paso, utilice el punto de enlace Create – Authorize con la cabecera x-transaction-channel-entry: XX.

Atributos obligatorios para Tarjeta Presente

Para obtener una lista completa de los atributos base (importe, moneda, etc.), consulte la Referencia de la API de Pagos. La siguiente tabla destaca los objetos específicos requeridos para las interacciones con tarjetas físicas:

Objeto	Atributo	Descripción	Obligatorio
`terminal`	`terminal_number`	El ID único del dispositivo que lee la tarjeta.	Sí
`card`	`entry_mode`	Establecer en `chip` o `magnetic_stripe`.	Sí
`card`	`cardholder_verification_method`	Utilizar `online_pin` o `no_cvm`.	Sí (Chip)
`card`	`emv`	La cadena de datos TLV cifrada del chip.	Sí (Chip)
`card`	`track_2`	Los datos de banda de la tarjeta capturados durante el deslizamiento o la lectura del chip.	Sí
`card`	`pin_block`	El bloque de PIN cifrado según ISO-9564.	Sí (PIN)
`card`	`ksn`	El DUKPT Key Serial Number para el descifrado del PIN.	Sí (PIN)

Elija el ejemplo siguiente que coincida con la interacción de hardware de su terminal.

Ejemplo 1: Chip + PIN Online

Se utiliza cuando el cliente inserta su tarjeta e introduce un PIN en el dispositivo.

{
  "idempotency_key": "5e019fb3-ebf8-4fab-b826-ece982236440",
  "request_id": "f0612285-9493-4c2c-a05a-00268a51ea3a",
  "order_id": "64af4497-864e-430c-9271-826601427a1d",
  "data": {
    "amount": 30960,
    "currency": "CLP",
    "customer_id": "ed2da8dd-1ba9-46e9-8501-f7987dcd9964",
    "payment": {
      "payment_id": "6137278d-28a6-4293-9343-c73fbb2d9bda",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MI*TIENDA",
      "card": {
        "number": "your_card_number",
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "seq_number": "000",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      },
      "terminal": {
        "terminal_number": "21000334"
      }
    }
  }
}

Ejemplo 2: Chip (Sin CVM)

Se utiliza para transacciones con chip donde no se requiere PIN ni firma.

{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "request_id": "f01db451-fe50-42d3-82d1-d64cedfdc7e8",
  "order_id": "d14c1129-964f-4fc7-b284-87d890820660",
  "data": {
    "amount": 30960,
    "currency": "CLP",
    "customer_id": "30ca15ad-db8b-4571-858e-dfe4cd46e3f8",
    "payment": {
      "payment_id": "your payment_id",
      "payment_method": "DIRECT_DEBIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MI*TIENDA",
      "card": {
        "number": "you_card_number",
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      },
      "terminal": {
        "terminal_number": "123456"
      }
    }
  }
}

Ejemplo 3: Banda magnética (Deslizar)

Se utiliza cuando se desliza la banda magnética de la tarjeta por el lector.

{
  "idempotency_key": "a61a2391-1372-46d9-9b8b-e3e265036367",
  "request_id": "140214fa-ff1d-4ecb-a6c8-2e1c828a944c",
  "order_id": "22e6bc02-0b55-4ed8-a131-a5e35b400297",
  "data": {
    "amount": 5000,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MI*TIENDA",
      "card": {
        "number": "5213120418132948",
        "expiration_month": "08",
        "expiration_year": "28",
        "entry_mode": "magnetic_stripe",
        "track_2": "5213120418132948=301220111379456001"
      },
      "terminal": {
        "terminal_number": "21000335"
      }
    }
  }
}

Paso 2: Verificar la respuesta

Si la operación tiene éxito, la API devuelve el estado y el payment_id único para la venta física.

{
  "status": "APPROVED",
  "payment_id": "6137278d-28a6-4293-9343-c73fbb2d9bda",
  "amount": 30960,
  "authorization_code": "204050",
  "reason_message": "captured"
}

Pasos siguientes

Ahora que ha procesado una venta de un solo paso, explore estas funciones avanzadas de Tarjeta Presente:

Preautorización en dos pasos: Aprenda a reservar fondos en una tarjeta física para su captura posterior.
Gestión de cuotas (plazos): Ofrezca la división del precio de compra en múltiples pagos directamente en el terminal.