# 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication). > Getnet proporciona una [Postman Collection](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-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](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) * [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types) * [Impuestos y regulaciones locales](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations) También puede utilizar [tarjetas de prueba](https://www.google.com/search?q=/en/articles%3Farticle%3Dtest-cards) 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](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) 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)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ## 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. Usted no necesita (y no puede) capturar manualmente cada plazo por separado. El desglose de los plazos y el calendario de liquidación son gestionados automáticamente por la red de tarjetas y el banco adquirente basándose en el tipo de plan seleccionado. 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)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ## 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: Esta guía demuestra el flujo de pago de un solo paso (Authorize & Capture). Sin embargo, los pagos a plazos también son totalmente compatibles con el flujo de dos pasos (Pre-authorized). Para utilizar el flujo Pre-authorized, siga las instrucciones de la guía de [Pagos Preautorizados](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-pre-authorized-payment), asegurándose de incluir los campos del objeto `installment` descritos a continuación en su petición de autorización. ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) 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. Si envía `card.number_token`, no necesita incluir la propiedad `card.number` en la petición. Puede utilizar el número de la tarjeta en formato original (raw) o la versión tokenizada, pero no ambos. Para obtener todos los detalles sobre la tokenización, consulte la documentación de [Tokenización y Vault](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault). ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/installments/POST/dpm/payments-gwproxy/v2/payments/quotes). La API de Getnet espera recibir los siguientes detalles en la petición: | Atributo | Descripción | Requerido | | ------------------------- | ------------------------------------------------------------------------------------------ | -------- | | `amount` | Importe total a pagar (en céntimos). | Sí | | `bin` | Primeros 6 o 9 dígitos de la tarjeta (preferiblemente 9; en el caso de Uruguay, se requieren 16 dígitos). | Sí | | `installment_type_filter` | Propiedad opcional para filtrar los resultados. Valores posibles: `no_interest` o `with_interest`. | No | Dependiendo de los requisitos de su mercado, puede enviar el `bin` (Bank Identification Number) de la tarjeta o, si ya ha tokenizado la tarjeta, puede utilizar `number_token` en su lugar. Ambos proporcionan la información necesaria para que la API devuelva las opciones de pago a plazos disponibles. El siguiente bloque de código muestra un ejemplo de petición: ```bash 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: ```json { "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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments) 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](https://predocs.globalgetnet.com/en/articles?article=taxes-and-regulations) para obtener más información. La siguiente tabla enumera los campos mínimos que necesita enviar: | Atributo | Descripción | Requerido | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------- | | `idempotency_key` | Identificador único para evitar cargos duplicados. | Sí | | `order_id` | ID de referencia del comercio utilizado para la conciliación. | Sí | | `request_id` | Identificador de rastreo para auditorías de idempotencia y seguimiento de soporte.| Recomendado | | `data.amount` | Importe de la transacción en céntimos. | Sí | | `data.currency` | Código de la divisa ISO utilizado en la transacción. | Sí | | `data.customer` | Detalles del cliente (nombre, correo electrónico, teléfono, documento, dirección de facturación completa). **Obligatorio en producción para evitar bloqueios del antifraude.** | Sí (Prod) | | `data.payment.payment_method` | Debe ser `CREDIT` o `DEBIT` para los pagos a plazos. | Sí | | `data.payment.transaction_type` | Define cómo se procesa la transacción. Varía según el país (consulte las secciones específicas de cada país). | Sí | | `data.payment.number_installments` | Número de plazos. | Sí | | `data.payment.card` | Conjunto de datos de la tarjeta (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`). | Sí | | `data.additional_data.installment` | Objeto de pago a plazos que contiene `schema`, `type` y `quote_id` del Paso 1. | Sí | | `data.additional_data.device` | Información del fingerprint del dispositivo (`ip_address`, `device_id`, `finger_print`) para análisis de antifraude. | Sí (Prod) | Los objetos necesarios para la validación del antifraude deben incluir los siguientes campos: | Objeto / Campo | Descripción | | -------------------------------------- | -------------------------------------------------- | | `customer.first_name` | Nombre del cliente | | `customer.last_name` | Apellido del cliente | | `customer.email` | Dirección de correo electrónico del cliente | | `customer.phone_number` | Número de teléfono (formato internacional) | | `customer.document_type` | Tipo de documento (ej., CPF, DNI, etc.) | | `customer.document_number` | Número de documento (sin puntuación) | | `customer.billing_address.street` | Nombre de la calle | | `customer.billing_address.number` | Número de la dirección | | `customer.billing_address.district` | Distrito o barrio | | `customer.billing_address.city` | Ciudad | | `customer.billing_address.state` | Estado o provincia | | `customer.billing_address.country` | Código del país (ISO) | | `customer.billing_address.postal_code` | Código postal | | `additional_data.device.ip_address` | Dirección IP del cliente | | `additional_data.device.device_id` | ID de la sesión del fingerprint del dispositivo (UUIDv4) | | `additional_data.device.finger_print` | Hash del fingerprint generado por el script de antifraude | > 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drisk-security-antifraud) para obtener detalles completos sobre la implementación. El siguiente bloque de código muestra un ejemplo de petición de pago a plazos: ```bash 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": "john.doe@example.com", "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`: ```json { "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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D). 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)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-combined-payments). * Lea acerca de los [Pagos con 3DS](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-3ds-authentication-20). * Explore los [Pagos Preautorizados](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-pre-authorized-payment).