Crear un pago Tarjeta Presente preautorizado

Procese una transacción completa de pago en dos pasos en un entorno Tarjeta Presente, primero autorizándola para reservar fondos en la tarjeta física y, posteriormente, capturándola para finalizar el cargo. Esta guía le orienta en el uso de la Getnet Regional API para flujos comunes integrados en el hardware, como hostelería o alquileres, donde el importe final de la transacción puede ajustarse tras la lectura inicial de la tarjeta.

Requisitos

Antes de seguir los pasos, debe:

Credenciales de la API: Póngase en contacto con el equipo de Soporte a la Integración para obtener su client_id y client_secret.
Token Bearer: Genere su token con sus credenciales utilizando el punto de enlace de Autenticación.
ID de hardware: Asegúrese de disponer de un terminal_number válido de su dispositivo físico registrado.

Getnet proporciona una Colección de Bruno/Postman para ayudarle a replicar estos casos de uso de hardware de forma local. También puede probar la API en el sandbox utilizando las referencias específicas de Tarjeta Presente disponibles en la documentación.

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 en dos pasos

El proceso de pago en dos pasos consiste en una autorización inicial para reservar fondos, seguida de una captura posterior para finalizar la liquidación. El siguiente diagrama de secuencia ilustra las interacciones entre su sistema integrado en el hardware y la Getnet Regional API, cubriendo la autorización inicial de la tarjeta física, la captura posterior a través de la API y la verificación del estado.

Getnet también admite la captura de pagos Tarjeta Presente en un solo paso. Para más detalles, consulte la guía Crear pagos Tarjeta Presente de un solo paso.

Paso 1: Autorizar el pago

Un pago en dos pasos comienza con la lectura física de la tarjeta. Establezca el data.payment.payment_method en DIRECT_CREDIT_AUTHORIZATION. Utilice el punto de enlace Create – Authorize con la cabecera x-transaction-channel-entry: XX.

Atributos de autorización específicos para

Para los campos base (importe, moneda, etc.) y las reglas de negocio regionales, consulte la Referencia de Preautorización.

Objeto	Atributo	Descripción	Obligatorio
`terminal`	`terminal_number`	El ID único del dispositivo de hardware físico.	Sí
`card`	`entry_mode`	Identifica cómo se ha leído la tarjeta (`chip` o `magnetic_stripe`).	Sí
`card`	`cardholder_verification_method`	Lógica de verificación del titular (`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í

Las secciones siguientes ofrecen ejemplos de cargas de datos (payloads) reales basados en diferentes métodos de entrada y verificación de tarjetas:

Ejemplo 1: Preautorización con Chip + PIN Online

Se utiliza cuando el cliente inserta su tarjeta e introduce un PIN en el terminal físico.

{
  "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_method": "DIRECT_CREDIT_AUTHORIZATION",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MI*TIENDA",
      "terminal": { "terminal_number": "21000334" },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "seq_number": "000",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    }
  }
}

Ejemplo 2: Preautorización con Chip (Sin PIN)

Se utiliza para transacciones con chip en las que no se requiere PIN.

{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "request_id": "f01db451-fe50-42d3-82d1-d64cedfdc7e8",
  "order_id": "d14c1129-964f-4fc7-b284-87d890820660",
  "data": {
    "amount": 15000,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT_AUTHORIZATION",
      "terminal": { "terminal_number": "123456" },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    }
  }
}

Ejemplo 3: Preautorización con banda magnética

Se utiliza para las tarjetas que se deslizan por la banda magnética del lector de hardware.

{
  "idempotency_key": "a61a2391-1372-46d9-9b8b-e3e265036367",
  "request_id": "140214fa-ff1d-4ecb-a6c8-2e1c828a944c",
  "data": {
    "amount": 10500,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT_AUTHORIZATION",
      "terminal": { "terminal_number": "21000335" },
      "card": {
        "number": "5213120418132948",
        "expiration_month": "08",
        "expiration_year": "28",
        "entry_mode": "magnetic_stripe",
        "track_2": "5213120418132948=301220111379456001"
      }
    }
  }
}

Al finalizar una autorización con éxito, recibirá un payment_id, que se utiliza para identificar esta transacción en el siguiente paso.

Paso 2: Capturar el pago

Una vez autorizada la interacción con la tarjeta física y determinado el importe final, debe capturar los fondos para finalizar la transacción. Utilice el punto de enlace de Captura para liquidar el cargo.

Al llamar al punto de enlace de captura, debe proporcionar el payment_id del paso de autorización y la idempotency_key. Si proporciona un importe (amount), este debe ser igual o inferior al importe autorizado originalmente.

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments/capture \
  --header 'authorization: Bearer <YOUR_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "capture-key-001",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "amount": 50000
}'

Ejemplo de respuesta con éxito:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "status": "CAPTURED",
  "reason_message": "captured",
  "captured_at": "2026-02-12T20:47:52.166Z"
}

Paso 3: Comprobar el estado del pago (Opcional)

La respuesta de autorización inicial mostrará el estado como AUTHORIZED. Una vez completado el paso de captura, este estado cambiará a CAPTURED. Puede verificar el estado final de la transacción en cualquier momento utilizando el punto de enlace Get Transaction.

Reautorización (ajustar un importe autorizado)

Después de una autorización con éxito, pero antes de la captura, puede modificar el importe reservado utilizando el punto de enlace de Ajuste. Esto es habitual en escenarios de hostelería y alquiler, donde el cargo final difiere del importe preautorizado originalmente.

El payment_method en una solicitud de ajuste siempre debe ser CREDIT_PRE_AUTHORIZATION. En esta fase solo se puede modificar el importe (amount); la interacción con la tarjeta ya ha finalizado.

Solicitud de ajuste

Campo	Tipo	Descripción	Obligatorio
`idempotency_key`	String	Clave única para esta solicitud de ajuste. Debe ser diferente de la clave de autorización original.	Sí
`request_id`	String (UUID)	Identificador único para esta operación de ajuste.	Sí
`data.amount`	Entero	El nuevo importe autorizado en céntimos. Puede ser superior o inferior al original.	Sí
`data.payment.payment_id`	String (UUID)	El `payment_id` de la respuesta de autorización original.	Sí
`data.payment.payment_method`	Enum	Debe ser `CREDIT_PRE_AUTHORIZATION`.	Sí

curl --request PATCH \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <YOUR_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "adjust-key-001",
  "request_id": "b9c1d2e3-f4a5-6789-b012-c3d4e5f60718",
  "data": {
    "amount": 65000,
    "payment": {
      "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
      "payment_method": "CREDIT_PRE_AUTHORIZATION"
    }
  }
}'

Respuesta de ajuste

Un ajuste con éxito devuelve HTTP 200 con los detalles de autorización actualizados, incluyendo el nuevo amount. Tras el ajuste, proceda al Paso 2 (Captura) utilizando el mismo payment_id.

{
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "status": "AUTHORIZED",
  "amount": 65000,
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY"
}

Pasos siguientes

Ahora que ha creado con éxito un pago Tarjeta Presente en dos pasos, explore más funciones de la Getnet Regional API:

Obtener el estado de la transacción: Consulte el estado actual de cualquier transacción autorizada o capturada.
Pagos con código QR: Ofrezca pagos alternativos en el terminal físico.
Pagos de un solo paso: Procese ventas estándar con chip y banda magnética.