Crear pagos Tarjeta Presente con cuotas

Esta guía explica cómo procesar transacciones de pago a plazos en un entorno Tarjeta Presente utilizando la Getnet Regional API. Las cuotas permiten a los clientes en un terminal físico dividir el precio total de la compra en importes más pequeños e iguales pagados a lo largo del tiempo, con la transacción asegurada por la presencia física 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 utilizando el punto de enlace de Autenticación.
Configuración del hardware: Asegúrese de que su terminal físico (POS/mPOS) esté registrado y dispongo de un terminal_number válido.

Getnet proporciona una Colección de Bruno/Postman para ayudarle a replicar estos casos de uso específicos de hardware de forma local.

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.

Entendiendo las cuotas en Tarjeta Presente

En un flujo Tarjeta Presente, un pago a plazos se crea como una transacción única. El desglose y la liquidación son gestionados automáticamente por la red de tarjetas en función del plan seleccionado durante la lectura física de la tarjeta.

Cómo funciona la liquidación (Settlement)

Las reglas de liquidación de las cuotas varían según la región y el esquema de la tarjeta. Para obtener un desglose completo de la financiación por parte del comercio frente a la del emisor y las restricciones regionales, consulte la Referencia de Cuotas.

Proceso de pago a plazos

El proceso consta de dos pasos principales: solicitar las ofertas de cuotas disponibles para la tarjeta específica insertada en el terminal y enviar el pago con la opción seleccionada.

Paso 1: Solicitar ofertas de cuotas disponibles

Antes de iniciar el pago, debe consultar las ofertas de cuotas disponibles para la tarjeta insertada en su lector de hardware utilizando el punto de enlace Get Installments.

La API espera los siguientes detalles:

Atributo	Descripción	Obligatorio
`amount`	Importe total de la transacción en céntimos.	Sí
`bin`	Los primeros 6 o 9 dígitos de la lectura de la tarjeta física.	Sí
`installment_type_filter`	Filtrar resultados por `no_interest` o `with_interest`.	No

Ejemplo de solicitud:

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/quotes \
  --header 'authorization: Bearer <YOUR_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
  "amount": 100000,
  "bin": "515590122",
  "installment_type_filter": "no_interest"
}'

Extraiga el quote_id y el schema de la respuesta para utilizarlos en la carga de datos del pago.

Paso 2: Crear el pago Tarjeta Presente con cuotas

Una vez que el cliente selecciona su plan de cuotas en el terminal, utilice el punto de enlace Create - Authorize para procesar el pago.

Para los flujos de cuotas Tarjeta Presente, debe establecer el data.payment.payment_method en DIRECT_CREDIT.

Atributos de cuotas específicos para

Para los campos base del pago, consulte la Referencia de la API de Pagos.

Objeto	Atributo	Descripción	Obligatorio
`terminal`	`terminal_number`	El ID único del hardware que lee la tarjeta.	Sí
`card`	`entry_mode`	Identifica cómo se ha leído la tarjeta (`chip`, `magnetic_stripe`, etc.).	Sí
`card`	`cardholder_verification_method`	Lógica de verificación del titular (`online_pin` o `no_cvm`).	Sí (Chip)
`card`	`emv`	La cadena TLV capturada del chip de la tarjeta.	Sí (Chip)
`additional_data.installment`	`quote_id`	El identificador único de la respuesta de la consulta de cuotas.	Sí
`additional_data.installment`	`schema`	El esquema de cuotas específico seleccionado.	Sí

Ejemplo 1: Pago en cuotas con Chip + PIN Online

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

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "RETAIL-ORDER-202",
  "data": {
    "amount": 100000,
    "currency": "CLP",
    "customer_id": "ed2da8dd-1ba9-46e9-8501-f7987dcd9964",
    "payment": {
      "payment_id": "payment_id_venda",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "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"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      }
    }
  }
}

Ejemplo 2: Pago en cuotas con Chip (Sin PIN)

Se utiliza para pagos a plazos en los que no es necesario introducir el PIN.

{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "data": {
    "amount": 100000,
    "currency": "CLP",
    "payment": {
      "payment_id": "payment_id_no_pin",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "terminal": {
        "terminal_number": "123456"
      },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      }
    }
  }
}

Ejemplo de respuesta

Si la operación tiene éxito, la API devuelve el desglose de las cuotas calculado.

{
  "status": "APPROVED",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "installments": {
    "number_installments": 3,
    "installment_value": 33334,
    "total_amount": 100002
  }
}

Paso 3: Comprobar el estado del pago (Opcional)

Los pagos a plazos que tengan éxito devolverán el estado APPROVED. Puede verificar el estado de la transacción en cualquier momento utilizando el punto de enlace Get Transaction.

Pasos siguientes

Aprenda a procesar Pagos de un solo paso.
Explore las Preautorizaciones en dos pasos.