# 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-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 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)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drecurring-cardholder-initiated) e [iniciados por el comercio](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drecurring-merchant-initiated). 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:
1. Registrar un perfil de cliente.
2. Crear un plan que define la programación del pago recurrente.
3. Realizar el Tokenization de los datos de la tarjeta para sustituir el número de tarjeta real por un token seguro.
4. Crear una suscripción que vincula al cliente con el plan con los detalles del método de pago.
5. 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](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types) 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/customers/post/dpm/customers-gwproxy/v1/customers) para registrar los datos del cliente:
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
--header 'authorization: Bearer ' \
--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": "john.doe@example.com",
"document_type": "CPF",
"document_number": "12345678900",
"phone_number": "+5511999999999"
}'
```
Ejemplo de respuesta:
```json
{
"seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
"customer_id": "customer-123",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/recurrence-plans/post/rpy/be-plan/v1/plans):
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/rpy/be-plan/v1/plans \
--header 'authorization: Bearer ' \
--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:
```json
{
"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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) para el Tokenization de la tarjeta:
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/tokens/card \
--header 'authorization: Bearer ' \
--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:
```json
{
"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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/subscriptions/post/rpy/be-subscription/v1/subscriptions):
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/subscriptions \
--header 'authorization: Bearer ' \
--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:
```json
{
"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": "john.doe@example.com"
},
"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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/subscriptions/get/rpy/be-subscription/v1/charges):
```bash
curl --request GET \
--url 'https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/charges?subscription_id=5d740ea0-b7d1-42f5-ad64-5a5521e12345' \
--header 'authorization: Bearer ' \
--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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dhandlingpayments-recurring-payments).
* Para obtener más información sobre Tokenization y almacenamiento seguro de tarjetas, consulte la [documentación de Tokenization y Vault](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault).
* Para obtener detalles completos de la referencia de la API, consulte la [Subscriptions API](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/subscriptions) y la [Recurrence Plans API](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/recurrence-plans) en la documentación de Swagger.