# Criar Pagamentos Recorrentes (Subscriptions Engine)

Este guia orienta você na configuração de pagamentos recorrentes usando o Getnet Subscriptions Engine. O motor processa automaticamente as cobranças recorrentes de acordo com os cronogramas de assinatura, sem exigir nenhuma ação do lojista ou do portador do cartão para cada transação.

## Pré-requisitos

Antes de seguir as etapas, você precisa:

  * Criar sua conta entrando em contato com a equipe de Suporte à Integração para obter suas credenciais de API `client_id` e `client_secret`.
  * Gerar seu token com suas credenciais usando o [Access Token endpoint](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-authentication).

> A Getnet fornece uma [Postman Collection](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-postman-collection) para ajudar você a replicar esses casos de uso localmente. Você também pode testar a API no sandbox usando a API Reference disponível na documentação.

<Callout type="warning">

O Subscriptions Engine é diferente dos pagamentos recorrentes [iniciados pelo portador do cartão (One Click)](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drecurring-cardholder-initiated) e [iniciados pelo lojista](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drecurring-merchant-initiated). Com o Subscriptions Engine, a Getnet processa automaticamente todas as cobranças recorrentes com base no cronograma do plano. Você não precisa acionar cada pagamento manualmente.

</Callout>

## Visão geral do processo

O Subscriptions Engine usa três componentes principais que trabalham juntos:

  * **Customer**: O consumidor do produto ou serviço oferecido na assinatura.
  * **Plan**: Define como os pagamentos recorrentes serão aplicados, incluindo o valor da parcela, a periodicidade e o número de parcelas.
  * **Subscription**: Vincula o cliente (customer) ao plano (plan) com os detalhes do método de pagamento.

Uma vez que você cria uma assinatura, o Getnet Subscriptions Engine processa automaticamente todas as cobranças recorrentes subsequentes de acordo com o cronograma do plano. O motor lida com o processamento de cobranças, tentativas de repetição (retries) e gerenciamento de ciclo de vida de forma automática.

O processo funciona da seguinte forma:

1.  Registrar um perfil de cliente.
2.  Criar um plano que define o cronograma de pagamento recorrente.
3.  Realizar o Tokenization dos dados do cartão para substituir o número real do cartão por um token seguro.
4.  Criar uma assinatura que vincula o cliente ao plano com os detalhes do método de pagamento.
5.  O motor processa automaticamente as cobranças recorrentes de acordo com o cronograma do plano.

O diagrama abaixo fornece uma visão geral do processo:

<img height="188" width="874" src="https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/documentations/diagram-create-recurring-payments-with-the-subscriptions-engine-1772648557609-70im4wms.png" />

## Etapas

Siga estas etapas para configurar uma assinatura de pagamento recorrente usando o Subscriptions Engine.

### Etapa 1: Registrar um cliente

O endpoint Create Customer registra um perfil de cliente na plataforma da Getnet. O cliente representa o consumidor do produto ou serviço oferecido na assinatura. Você precisará deste ID de cliente para vinculá-lo a uma assinatura posteriormente.

A tabela a seguir descreve os campos obrigatórios para a criação de um cliente:

| Campo             | Tipo          | Requerido | Descrição                                                                                                                    |
| :---------------- | :------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `seller_id`       | string (UUID) | Sim      | Seu identificador de lojista.                                                                                                  |
| `customer_id`     | string        | Não      | Seu identificador personalizado para o cliente. Se não for fornecido, a Getnet gerará um.                                      |
| `first_name`      | string        | Sim      | Primeiro nome do cliente (máx. 40 caracteres).                                                                                 |
| `last_name`       | string        | Sim      | Sobrenome do cliente (máx. 80 caracteres).                                                                                     |
| `document_type`   | string        | Sim      | Tipo de documento do cliente. Consulte os [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types) para os valores disponíveis. |
| `document_number` | string        | Sim      | Número do documento do cliente sem máscara (11-15 caracteres).                                                                 |
| `email`           | string        | Não      | Endereço de e-mail do cliente.                                                                                                 |
| `phone_number`    | string        | Não      | Número de telefone do cliente sem máscara (máx. 15 caracteres).                                                                |

Use o [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 os detalhes do cliente:

```bash
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": "john.doe@example.com",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'
```

Exemplo de resposta:

```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"
}
```

### Etapa 2: Criar um plano

O endpoint Create Plan registra um plano de recorrência que define como os pagamentos recorrentes serão aplicados. O plano especifica o valor a ser cobrado, a frequência de cobrança e o número de ciclos de cobrança.

A tabela a seguir descreve os campos obrigatórios para a criação de um plano:

| Campo           | Tipo          | Requerido | Descrição                                                                                                                                              |
| :-------------- | :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seller_id`     | string (UUID) | Sim      | Seu identificador de lojista.                                                                                                                            |
| `name`          | string        | Sim      | Nome do plano (mín. 3 caracteres).                                                                                                                       |
| `description`   | string        | Não      | Descrição do plano.                                                                                                                                      |
| `amount`        | integer       | Sim      | Valor a ser cobrado na menor unidade monetária (por exemplo, centavos).                                                                                  |
| `currency`      | string        | Sim      | Código da moeda (por exemplo, `BRL`, `ARS`, `CLP`, `MXN`).                                                                                               |
| `payment_types` | array         | Sim      | Métodos de pagamento aceitos. Valores: `credit_card`, `debit_card`.                                                                                      |
| `period`        | object        | Sim      | Configuração do período de cobrança. Veja a tabela abaixo.                                                                                               |
| `product_type`  | string        | Não      | Tipo de produto. Valores: `cash_carry`, `digital_content`, `digital_goods`, `gift_card`, `physical_goods`, `renew_subs`, `shareware`, `service`.         |

O objeto `period` define a frequência de cobrança:

| Campo                  | Tipo    | Requerido | Descrição                                    |
| :--------------------- | :------ | :------- | :--------------------------------------------- |
| `period.type`          | string  | Sim      | Periodicidade de cobrança. Veja os valores abaixo. |
| `period.billing_cycle` | integer | Sim      | Número de ciclos de cobrança (parcelas).       |

A periodicidade é definida no campo `period.type`:

| Periodicidade   | Campo: `period.type` | Descrição                                   |
| :-------------- | :------------------- | :-------------------------------------------- |
| **Anual** | `yearly`             | Cobrado uma vez por ano                       |
| **Mensal** | `monthly`            | Cobrado uma vez por mês                       |
| **Bimestral** | `bimonthly`          | Cobrado uma vez a cada 2 meses                |
| **Trimestral** | `quarterly`          | Cobrado uma vez a cada 3 meses                |
| **Semestral** | `semesterly`         | Cobrado uma vez a cada 6 meses                |
| **Específico** | `specific`           | Ciclo de cobrança específico em dias          |

Use o [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 <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"
}'
```

Exemplo de resposta:

```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"
}
```

> Salve o `plan_id` da resposta. Você precisará deste ID ao criar a assinatura na Etapa 4.

### Etapa 3: Tokenization dos dados do cartão

O endpoint Generate Token converte o número real de um cartão em um token seguro. O Tokenization substitui o número real do cartão por um token, garantindo a conformidade com o PCI DSS e a segurança da transação. O CVV não é obrigatório para a geração do token.

A tabela a seguir descreve os campos obrigatórios para realizar o Tokenization de um cartão:

| Campo         | Tipo   | Requerido | Descrição                                  |
| :------------ | :----- | :------- | :------------------------------------------- |
| `card_number` | string | Sim      | Número do cartão (13 a 19 dígitos).          |
| `customer_id` | string | Não      | Identificador do cliente gerado na Etapa 1.  |

Use o [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 o Tokenization do cartão:

```bash
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"
}'
```

Exemplo de resposta:

```json
{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c"
}
```

> Salve o `number_token` da resposta. Você precisará deste token ao criar a assinatura na Etapa 4.

### Etapa 4: Criar uma assinatura

O endpoint Create Subscription vincula um cliente a um plano com detalhes do método de pagamento. Uma vez criada, o Subscriptions Engine processa automaticamente as cobranças recorrentes de acordo com o cronograma do plano. A assinatura permanece com o status `scheduled` até a `installment_start_date`, quando a cobrança é iniciada.

A tabela a seguir descreve os campos obrigatórios para criar uma assinatura:

| Campo                    | Tipo          | Requerido | Descrição                                                                                                                                           |
| :----------------------- | :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seller_id`              | string (UUID) | Sim      | Seu identificador de lojista.                                                                                                                         |
| `customer_id`            | string        | Sim      | Identificador do cliente gerado na Etapa 1.                                                                                                           |
| `plan_id`                | string (UUID) | Sim      | Identificador do plano gerado na Etapa 2.                                                                                                             |
| `installment_start_date` | string        | Não      | Data de início de cobrança da assinatura (formato: `YYYY-MM-DD`). Até esta data, a assinatura permanece com o status `scheduled`.                     |
| `subscription`           | object        | Sim      | Configuração do método de pagamento. Veja a tabela abaixo.                                                                                            |

O objeto `subscription.payment_type.credit` contém os detalhes do cartão:

| Campo                   | Tipo    | Requerido | Descrição                                                                         |
| :---------------------- | :------ | :------- | :---------------------------------------------------------------------------------- |
| `transaction_type`      | string  | Sim      | Tipo de transação. Use `FULL` para pagamento integral.                              |
| `number_installments`   | integer | Sim      | Número de parcelas por cobrança.                                                    |
| `card.number_token`     | string  | Sim      | Número do cartão após o Tokenization na Etapa 3.                                    |
| `card.brand`            | string  | Sim      | Bandeira do cartão. Valores: `VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD`.      |
| `card.cardholder_name`  | string  | Sim      | Nome do portador do cartão conforme impresso no cartão (máx. 26 caracteres).        |
| `card.expiration_month` | string  | Sim      | Mês de expiração com dois dígitos (por exemplo, `12`).                              |
| `card.expiration_year`  | string  | Sim      | Ano de expiração com dois dígitos (por exemplo, `30`).                              |
| `card.security_code`    | string  | Sim      | Código de segurança do cartão (CVV).                                                |

Use o [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 <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
      }
    }
  }
}'
```

Exemplo de resposta:

```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"
  }
}
```

### Etapa 5: Monitorar cobranças (opcional)

O endpoint Get Charges recupera uma lista de cobranças processadas para uma assinatura. Após a criação da assinatura, o motor processa automaticamente todas as cobranças recorrentes de acordo com o cronograma do plano. Use este endpoint para monitorar o status das cobranças e o histórico de pagamentos.

Use o [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 <your-token>' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8'
```

## Considerações importantes

  * Se a data da solicitação de alteração estiver dentro do período, ela será contada a partir da data da solicitação + 1 dia.
  * Cobranças com agendamento que estão em processo de repetição (retry) e tiveram o pagamento negado serão desconsideradas na validação do período.
  * O motor processa apenas cobranças para assinaturas ativas.
  * O motor usa o método de pagamento especificado ao criar a assinatura. Certifique-se de que o cartão permaneça válido e ativo.

## Veja também

  * Para obter mais informações sobre pagamentos recorrentes, incluindo disponibilidade por país e outras opções de implementação, consulte [Recurring Payments](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dhandlingpayments-recurring-payments).
  * Para saber mais sobre Tokenization e armazenamento seguro de cartões, consulte a [documentação de Tokenization e Vault](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault).
  * Para obter detalhes completos de referência da API, consulte a [Subscriptions API](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/subscriptions) e a [Recurrence Plans API](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/recurrence-plans) na documentação do Swagger.