Crear Pagos Recurrentes (Subscriptions Engine)

Esta guía le orienta en la configuración de pagos recurrentes utilizando el Getnet Subscriptions Engine. El motor procesa automáticamente los cargos recurrentes de acuerdo con las programaciones de la suscripción sin requerir ninguna acción por parte del comercio o del titular de la tarjeta para cada transacción.

Requisitos previos

Antes de seguir los pasos, debe:

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

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

El Subscriptions Engine es diferente de los pagos recurrentes iniciados por el titular de la tarjeta (One Click) e iniciados por el comercio. Con el Subscriptions Engine, Getnet procesa automáticamente todos los cargos recurrentes en función de la programación del plan. No necesita activar cada pago manualmente.

Resumen del proceso

El Subscriptions Engine utiliza tres componentes principales que trabajan juntos:

Customer: El consumidor del producto o servicio ofrecido en la suscripción.
Plan: Define cómo se aplicarán los pagos recurrentes, incluyendo el importe de la cuota, la periodicidad y el número de cuotas.
Subscription: Vincula al cliente (customer) con el plan (plan) con los detalles del método de pago.

Una vez que crea una suscripción, el Getnet Subscriptions Engine procesa automáticamente todos los cargos recurrentes posteriores de acuerdo con la programación del plan. El motor gestiona el procesamiento de cargos, los reintentos (retries) y la gestión del ciclo de vida de forma automática.

El proceso funciona de la siguiente manera:

Registrar un perfil de cliente.
Crear un plan que define la programación del pago recurrente.
Realizar el Tokenization de los datos de la tarjeta para sustituir el número de tarjeta real por un token seguro.
Crear una suscripción que vincula al cliente con el plan con los detalles del método de pago.
El motor procesa automáticamente los cargos recurrentes de acuerdo con la programación del plan.

El siguiente diagrama ofrece un resumen del proceso:

Pasos

Siga estos pasos para configurar una suscripción de pago recurrente utilizando el Subscriptions Engine.

Paso 1: Registrar un cliente

El endpoint Create Customer registra un perfil de cliente en la plataforma de Getnet. El cliente representa al consumidor del producto o servicio ofrecido en la suscripción. Necesitará este ID de cliente para vincularlo a una suscripción más adelante.

La siguiente tabla describe los campos obligatorios para crear un cliente:

Campo	Tipo	Requerido	Descripción
`seller_id`	string (UUID)	Sí	Su identificador de comercio.
`customer_id`	string	No	Su identificador personalizado para el cliente. Si no se proporciona, Getnet generará uno.
`first_name`	string	Sí	Nombre del cliente (máx. 40 caracteres).
`last_name`	string	Sí	Apellido del cliente (máx. 80 caracteres).
`document_type`	string	Sí	Tipo de documento del cliente. Consulte los Tipos de documento para ver los valores disponibles.
`document_number`	string	Sí	Número de documento del cliente sin máscara (11-15 caracteres).
`email`	string	No	Dirección de correo electrónico del cliente.
`phone_number`	string	No	Número de teléfono del cliente sin máscara (máx. 15 caracteres).

Utilice el Create Customer endpoint para registrar los datos del cliente:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'

Ejemplo de respuesta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999",
  "created_at": "2025-11-06T10:30:00.000Z"
}

Paso 2: Crear un plan

El endpoint Create Plan registra un plan de recurrencia que define cómo se aplicarán los pagos recurrentes. El plan especifica el importe a cobrar, la frecuencia de facturación y el número de ciclos de facturación.

La siguiente tabla describe los campos obligatorios para crear un plan:

Campo	Tipo	Requerido	Descripción
`seller_id`	string (UUID)	Sí	Su identificador de comercio.
`name`	string	Sí	Nombre del plan (mín. 3 caracteres).
`description`	string	No	Descripción del plan.
`amount`	integer	Sí	Importe a cobrar en la unidad monetaria más pequeña (por ejemplo, céntimos).
`currency`	string	Sí	Código de divisa (por ejemplo, `BRL`, `ARS`, `CLP`, `MXN`).
`payment_types`	array	Sí	Métodos de pago aceptados. Valores: `credit_card`, `debit_card`.
`period`	object	Sí	Configuración del período de facturación. Consulte la tabla a continuación.
`product_type`	string	No	Tipo de producto. Valores: `cash_carry`, `digital_content`, `digital_goods`, `gift_card`, `physical_goods`, `renew_subs`, `shareware`, `service`.

El objeto period define la frecuencia de facturación:

Campo	Tipo	Requerido	Descripción
`period.type`	string	Sí	Periodicidad de facturación. Consulte los valores a continuación.
`period.billing_cycle`	integer	Sí	Número de ciclos de facturación (cuotas).

La periodicidad se define en el campo period.type:

Periodicidad	Campo: `period.type`	Descripción
Anual	`yearly`	Se cobra una vez al año
Mensual	`monthly`	Se cobra una vez al mes
Bimestral	`bimonthly`	Se cobra una vez cada 2 meses
Trimestral	`quarterly`	Se cobra una vez cada 3 meses
Semestral	`semesterly`	Se cobra una vez cada 6 meses
Específico	`specific`	Ciclo de facturación específico en días

Utilice el Create Plan endpoint:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/rpy/be-plan/v1/plans \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "name": "Premium Monthly Plan",
  "description": "Monthly subscription for premium features",
  "amount": 9900,
  "currency": "BRL",
  "payment_types": ["credit_card"],
  "period": {
    "type": "monthly",
    "billing_cycle": 12
  },
  "product_type": "service"
}'

Ejemplo de respuesta:

{
  "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "name": "Premium Monthly Plan",
  "description": "Monthly subscription for premium features",
  "amount": 9900,
  "currency": "BRL",
  "payment_types": "credit_card",
  "period": {
    "type": "monthly",
    "billing_cycle": 12
  },
  "product_type": "service",
  "status": "active",
  "create_date": "2025-11-06T10:35:00.000Z"
}

Guarde el plan_id de la respuesta. Necesitará este ID al crear la suscripción en el Paso 4.

Paso 3: Tokenization de los datos de la tarjeta

El endpoint Generate Token convierte el número de tarjeta real en un token seguro. El Tokenization sustituye el número de tarjeta real por un token, garantizando el cumplimiento de la normativa PCI DSS y la seguridad de la transacción. El CVV no es obligatorio para la generación del token.

La siguiente tabla describe los campos obligatorios para realizar el Tokenization de una tarjeta:

Campo	Tipo	Requerido	Descripción
`card_number`	string	Sí	Número de tarjeta (13-19 dígitos).
`customer_id`	string	No	Identificador de cliente generado en el Paso 1.

Utilice el Card Tokenization endpoint para el Tokenization de la tarjeta:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/tokens/card \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "card_number": "5155901222280001",
  "customer_id": "customer-123"
}'

Ejemplo de respuesta:

{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c"
}

Guarde el number_token de la respuesta. Necesitará este token al crear la suscripción en el Paso 4.

Paso 4: Crear una suscripción

El endpoint Create Subscription vincula un cliente a un plan con los detalles del método de pago. Una vez creada, el Subscriptions Engine procesa automáticamente los cargos recurrentes de acuerdo con la programación del plan. La suscripción permanece en estado scheduled hasta la installment_start_date, cuando comienza la facturación.

La siguiente tabla describe los campos obligatorios para crear una suscripción:

Campo	Tipo	Requerido	Descripción
`seller_id`	string (UUID)	Sí	Su identificador de comercio.
`customer_id`	string	Sí	Identificador de cliente generado en el Paso 1.
`plan_id`	string (UUID)	Sí	Identificador del plan generado en el Paso 2.
`installment_start_date`	string	No	Fecha de inicio de facturación de la suscripción (formato: `YYYY-MM-DD`). Hasta esta fecha, la suscripción permanece en estado `scheduled`.
`subscription`	object	Sí	Configuración del método de pago. Consulte la tabla a continuación.

El objeto subscription.payment_type.credit contiene los detalles de la tarjeta:

Campo	Tipo	Requerido	Descripción
`transaction_type`	string	Sí	Tipo de transacción. Utilice `FULL` para el pago íntegro.
`number_installments`	integer	Sí	Número de cuotas por cargo.
`card.number_token`	string	Sí	Número de la tarjeta tras el Tokenization en el Paso 3.
`card.brand`	string	Sí	Marca de la tarjeta. Valores: `VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD`.
`card.cardholder_name`	string	Sí	Nombre del titular de la tarjeta tal como figura en ella (máx. 26 caracteres).
`card.expiration_month`	string	Sí	Mes de caducidad de dos dígitos (por ejemplo, `12`).
`card.expiration_year`	string	Sí	Año de caducidad de dos dígitos (por ejemplo, `30`).
`card.security_code`	string	Sí	Código de seguridad de la tarjeta (CVV).

Utilice el Create Subscription endpoint:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/subscriptions \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd",
  "installment_start_date": "2025-11-15",
  "subscription": {
    "payment_type": {
      "credit": {
        "transaction_type": "FULL",
        "card": {
          "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
          "cardholder_name": "John Doe",
          "security_code": "123",
          "brand": "MASTERCARD",
          "expiration_month": "12",
          "expiration_year": "30"
        },
        "number_installments": 1
      }
    }
  }
}'

Ejemplo de respuesta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "order_id": "ORDER-10187383",
  "installment_start_date": "2025-11-15",
  "create_date": "2025-11-06T10:40:00.000Z",
  "payment_date": 15,
  "next_scheduled_date": "2025-11-15T00:00:00.000Z",
  "status": "created",
  "status_details": "Subscription Plan flex successfully created",
  "subscription": {
    "subscription_id": "5d740ea0-b7d1-42f5-ad64-5a5521e12345"
  },
  "customer": {
    "customer_id": "customer-123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "plan": {
    "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd",
    "name": "Premium Monthly Plan",
    "amount": 9900,
    "currency": "BRL"
  }
}

Paso 5: Supervisar cargos (opcional)

El endpoint Get Charges recupera una lista de cargos procesados para una suscripción. Tras la creación de la suscripción, el motor procesa automáticamente todos los cargos recurrentes de acuerdo con la programación del plan. Utilice este endpoint para supervisar el estado de los cargos y el historial de pagos.

Utilice el Get Charges endpoint:

curl --request GET \
  --url 'https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/charges?subscription_id=5d740ea0-b7d1-42f5-ad64-5a5521e12345' \
  --header 'authorization: Bearer <your-token>' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8'

Consideraciones importantes

Si la fecha de la solicitud de modificación se encuentra dentro del período, se contará a partir de la fecha de la solicitud + 1 día.
Los cargos programados que se encuentren en proceso de reintento (retry) y cuyo pago haya sido denegado no se tendrán en cuenta en la validación del período.
El motor solo procesa cargos de suscripciones activas.
El motor utiliza el método de pago especificado al crear la suscripción. Asegúrese de que la tarjeta sigue siendo válida y está activa.

Consulte también

Para obtener más información sobre pagos recurrentes, incluyendo disponibilidad por país y otras opciones de implementación, consulte Recurring Payments.
Para obtener más información sobre Tokenization y almacenamiento seguro de tarjetas, consulte la documentación de Tokenization y Vault.
Para obtener detalles completos de la referencia de la API, consulte la Subscriptions API y la Recurrence Plans API en la documentación de Swagger.