Crear Pagos a Plazos (Installments)

Esta guía explica cómo procesar transacciones de pago a plazos utilizando la Global API de Getnet. Los pagos a plazos permiten a los clientes dividir el precio total de la compra en varios importes menores e iguales, pagados a lo largo de un período de tiempo acordado, proporcionando una mayor flexibilidad en lugar de requerir el pago total por adelantado. La implementación de este método de pago depende de la disponibilidad de soporte de la tarjeta y de las regulaciones regionales.

Requisitos

Antes de seguir los pasos, necesita:

• Crear su cuenta poniéndose en contacto con el equipo de Soporte de Integración para obtener sus credenciales de la API client_id y client_secret.
• Generar su token con sus credenciales utilizando el endpoint de Authentication.

Getnet proporciona una Postman Collection para ayudarle a replicar estos casos de uso localmente. También puede probar la API en el entorno sandbox utilizando la API Reference disponible en la documentación.

Especificidades de los Casos de Uso

Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. Asegúrese de revisar los recursos a continuación antes de pasar a producción:

• Códigos de divisa
• Tipos de documento
• Impuestos y regulaciones locales

También puede utilizar tarjetas de prueba para simular escenarios específicos. Puede encontrar más información sobre los requisitos específicos para cada país en la sección de Developer Resources de la documentación de Getnet.

Disponibilidad de la plataforma

El soporte para pagos a plazos varía según el país y la marca de la tarjeta. Para obtener una referencia completa de las reglas de pagos a plazos, los esquemas de tarjetas disponibles y los tipos de planes por mercado, consulte las Reglas y Disponibilidad de Pagos a Plazos (Installments).

Entendiendo Cómo Funcionan los Pagos a Plazos

Un pago a plazos se crea como una única transacción de pago, no como múltiples autorizaciones separadas. Cuando crea un pago a plazos, realiza una sola llamada a la API, y la liquidación/captura es gestionada automáticamente por la red de tarjetas y los bancos emisores según el tipo de plan de pago a plazos.

Cómo Funciona la Liquidación

Cada país tiene diferentes tipos de planes de pago a plazos con esquemas y modelos de liquidación específicos. El proceso de liquidación varía dependiendo del plan seleccionado:

• Algunos planes liquidan el importe total al comercio de una sola vez, y el banco cobra los plazos al cliente a lo largo del tiempo.
• Otros planes liquidan al comercio en plazos mensuales de forma automática.
• El cliente puede o no pagar intereses dependiendo del tipo de plan.

Para obtener información detallada sobre los planes de pago a plazos, los esquemas y los modelos de liquidación disponibles en cada país, consulte las Reglas y Disponibilidad de Pagos a Plazos (Installments).

Proceso de Pago a Plazos

Esta sección le orienta en la creación de una transacción de pago a plazos. El proceso implica dos pasos principales: solicitar las ofertas de pago a plazos disponibles y enviar el pago con la opción de pago a plazos seleccionada.

El siguiente diagrama ilustra el flujo completo del pago a plazos:

Generación de Quote ID

Al implementar pagos a plazos en los mercados de Argentina y Chile, es obligatorio incluir el valor quote_id en las peticiones a la API de pago a plazos para que las transacciones puedan procesarse correctamente. Este campo se utiliza para calcular las tasas de interés, los impuestos y otros requisitos antes de la autorización del pago.

Cálculos de tasas de interés

Para este proceso, existen dos alternativas para comercios y partners, dependiendo de sus necesidades:

• Calculado por el Usuario: El comercio calcula las tasas de interés externamente e informa a la API a través del campo amount. En las llamadas a la API, el quote_id debe generarse como no_interest.
• Calculado por Getnet: El comercio confía en los cálculos de las tasas de interés de Getnet, que incluyen información actualizada del emisor/gobierno, y por tanto no tendrá que calcularlas externamente. En las llamadas a la API, el quote_id debe generarse como with_interest.

Tokenizar los Datos de la Tarjeta (Opcional)

En lugar de enviar el número de la tarjeta en formato original (raw) en su petición de pago, puede utilizar la tokenización para mejorar la seguridad y reducir el alcance del cumplimiento del PCI DSS. Para utilizar una tarjeta tokenizada:

1. Tokenice la tarjeta llamando al endpoint de Card Tokenization con el card_number y el customer_id.
2. En su petición de pago, reemplace el campo card.number por card.number_token utilizando el valor del token recibido del endpoint de tokenización.

Paso 1: Solicitar Ofertas de Pagos a Plazos Disponibles

Antes de iniciar un pago, debe consultar las ofertas de pago a plazos disponibles para la tarjeta y el importe de la transacción seleccionados utilizando el endpoint de Get Installments.

La API de Getnet espera recibir los siguientes detalles en la petición:

El siguiente bloque de código muestra un ejemplo de petición:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/quotes \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "amount": 100000,
  "bin": "515590122",
  "installment_type_filter": "no_interest"
}'

Ejemplo de respuesta con las opciones de pago a plazos disponibles:

{
  "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b",
  "amount": 100000,
  "currency": "BRL",
  "credits": [
    {
      "number_installments": 1,
      "installment_value": 100000,
      "total_amount": 100000,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 3,
      "installment_value": 33334,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 6,
      "installment_value": 16667,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    }
  ]
}

Necesitará extraer las siguientes propiedades de la respuesta para utilizarlas en el siguiente paso:

• quote_id - Identificador único para la cotización del pago a plazos
• schema - Código que agrupa los créditos por categoría

Paso 2: Crear el Pago a Plazos

Una vez que el cliente haya seleccionado su opción de pago a plazos preferida, utilice el endpoint de Create - Authorize para procesar el pago.

La API de Getnet espera recibir los detalles del pago a plazos dentro del objeto additional_data. Si se incluye el objeto installment, el pago se realizará de acuerdo con el número de plazos previamente definido; de lo contrario, el pago se realizará en un solo plazo.

Requisitos específicos del país: Algunos mercados pueden requerir campos obligatorios adicionales. En Uruguay debe incluir un array rates y proporcionar un regional_regulation_code. El regional_regulation_code es un array donde cada entrada tiene un code y un invoice. El invoice acepta hasta 9 caracteres alfanuméricos. Recomendamos usar solo números. Revise la referencia de Taxes and Regulations para obtener más información.

La siguiente tabla enumera los campos mínimos que necesita enviar:

Los objetos necesarios para la validación del antifraude deben incluir los siguientes campos:

Los datos de antifraude son obligatorios para entornos de producción. Las transacciones que carezcan del fingerprint del dispositivo o de la información del cliente serán bloqueadas automáticamente por los equipos de antifraude para prevenir el fraude. Consulte la documentación de Antifraude para obtener detalles completos sobre la implementación.

El siguiente bloque de código muestra un ejemplo de petición de pago a plazos:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 100000,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "09",
        "expiration_year": "30",
        "cardholder_name": "Card Holder",
        "security_code": "517"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      },
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Ejemplo de respuesta con status como APPROVED:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "amount": 100000,
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-10-31T13:40:47.382Z",
  "transaction_id": "MCC50205G1020",
  "original_transaction_id": "MCC50205G1020",
  "authorized_at": "2025-10-31T13:40:47.382Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "204050",
  "acquirer_transaction_id": "405030304060404030501060",
  "installments": {
    "number_installments": 3,
    "installment_value": 33334,
    "total_amount": 100002
  }
}

Paso 3: Comprobar el Estado del Pago (Opcional)

La respuesta de Create - Authorize mostrará el estado como APPROVED para los pagos a plazos realizados con éxito.

Debido a que algunos pagos se procesan de forma asíncrona, el estado puede cambiar con el tiempo. Para obtener el estado más reciente de una transacción, utilice el endpoint de Get Transaction.

Para obtener actualizaciones en tiempo real sin necesidad de hacer polling, se recomienda utilizar Webhooks para recibir notificaciones sobre cada cambio de estado.

Requisitos de Pago a Plazos Específicos del País

Cada mercado tiene opciones de pago a plazos, tipos de planes y requisitos de implementación específicos. Para obtener información detallada sobre las reglas de pago a plazos, los planes disponibles por marca de tarjeta y los requisitos específicos de cada país (incluyendo los valores de campo obligatorios para el objeto installment), consulte las Reglas y Disponibilidad de Pagos a Plazos (Installments).

Próximos Pasos

Ahora que ha creado con éxito un pago a plazos, puede explorar más funciones de la Global API de Getnet:

• Aprenda cómo crear Pagos Combinados.
• Lea acerca de los Pagos con 3DS.
• Explore los Pagos Preautorizados.