Pular para o conteúdo principal
O Localpayment permite criar planos de assinatura fixos para cenários de cobrança recorrente padronizados. Este guia detalha como configurar planos de assinatura por meio da API do Localpayment, que podem então ser associados às assinaturas dos clientes para uma cobrança consistente e automatizada.

Antes de começar

Certifique-se de ter:

Credenciais da API

Credenciais de API e token de acesso válidos para autenticação.

Configuração da conta

Configuração adequada da conta para o país de destino e verificação da empresa.

Lista branca de IPs

Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

Endpoint do webhook

Configure um URL de webhook para receber notificações de pagamento.

Passo 1: Crie um plano de assinatura

Para criar um novo plano de assinatura, envie uma solicitação POST para o endpoint Criar plano de assinatura.

Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave:

Frequências de faturamento suportadas

Diário

Cobrar dos clientes diariamente. Ideal para serviços com uso diário ou assinaturas de curto prazo.Envie a propriedade autoRecurring.type com o valor: day

Mensal

Cobrança mensal recorrente para a maioria dos produtos SaaS, serviços de associação e caixas de assinatura.Envie a propriedade autoRecurring.type com o valor: month

Personalizado (sob demanda)

Cobrança sob demanda para cenários de uso variável. Ideal para serviços de pagamento conforme o uso ou baseados em consumo.Envie a propriedade autoRecurring.type com o valor: custom

Exemplo de solicitação

Abaixo está um exemplo usando curl:
curl
Veja todos os parâmetros disponíveis na solicitação.

Etapa 2: Lidar com a resposta

Resposta bem-sucedida

Um plano de assinatura criado com sucesso retorna todos os detalhes do plano:

Campos de resposta principais

Resposta de erro

Quando a criação do plano de assinatura falhar, você receberá informações detalhadas sobre o erro:

Etapa 3: Rastrear o status da transação

Após criar um plano de assinatura, monitore o status dele por meio destes métodos:

Webhooks (Recomendado)

Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

Endpoint da API de Status

Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

Visualização do Business Portal

Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

Códigos de status comuns

Referência completaConsulte todos os códigos de status em nossa Documentação de Status da Transação.

Testando sua integração

Cenários de teste

Verifique se sua integração lida com esses cenários:
  1. Criação de plano bem-sucedida: Criação de plano padrão com parâmetros válidos.
  2. Estrutura de preços por níveis: Criação de múltiplos planos com preços diferentes.
  3. Diversas opções de cobrança: planos diários, mensais e personalizados sob demanda.
  4. Erros de validação: Campos obrigatórios ausentes, valores inválidos, países não suportados.
  5. Associação de Assinaturas: Testando se os planos podem ser vinculados com sucesso às assinaturas.

Próximos passos

Após criar um plano de assinatura, você poderá precisar realizar ações adicionais:

Criar assinatura com plano

Utilize o internalId do plano como parâmetro planId para criar assinaturas de clientes com o seu novo plano.

Atualizar plano de assinatura

Modifique os detalhes de um plano existente, mantendo as associações com as assinaturas ativas.
Última modificação em 10 de novembro de 2026