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.

A Getnet fornece uma 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.

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:

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:

Use o Create Customer endpoint para registrar os detalhes do 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"
}'

Exemplo de resposta:

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

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:

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

A periodicidade é definida no campo period.type:

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

Exemplo de resposta:

{
  "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:

Use o Card Tokenization endpoint para o Tokenization do cartão:

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:

{
  "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:

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

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

Exemplo de resposta:

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

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:

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.
• Para saber mais sobre Tokenization e armazenamento seguro de cartões, consulte a documentação de Tokenization e Vault.
• Para obter detalhes completos de referência da API, consulte a Subscriptions API e a Recurrence Plans API na documentação do Swagger.