Pular para o conteúdo principal
O Localpayment permite que os comerciantes configurem assinaturas de pagamento recorrente com cartões de crédito e débito, oferecendo suporte tanto a planos fixos quanto a cenários de cobrança personalizados em vários países. Este guia descreve o processo de criação de uma assinatura por meio da API do Localpayment, detalhando os parâmetros obrigatórios, o tratamento das respostas e a interpretação dos códigos de status.

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 uma assinatura

Para criar uma nova assinatura, você precisará enviar uma solicitação POST para o endpoint Criar uma assinatura.

Parâmetros-chave da solicitação

A solicitação exige vários parâmetros-chave, dependendo de você estar criando uma assinatura de plano fixo ou uma assinatura personalizada:

Tipos de assinatura

  • Assinatura de plano fixo: Use quando você tiver planos de assinatura predefinidos criados por meio do endpoint Criar plano de assinatura.
  • Assinatura personalizada: Use para cenários de faturamento variável em que cada pagamento pode ter valor ou prazo diferente.

Códigos de métodos de pagamento

Em todos os países, paymentMethod.code identifica o país, a bandeira do cartão e o produto (crédito ou débito); portanto, envie o código que corresponde ao cartão e ao country da assinatura. No Peru, onde os cartões são aceitos em duas moedas, o código também deve corresponder à currency: por exemplo, um cartão de crédito Visa usa 6000 com PEN e 6004 com USD. Consulte Códigos de métodos de pagamento com cartão para ver os códigos de todos os países.

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

Uma resposta bem-sucedida inclui informações detalhadas sobre a assinatura e identificadores:

Campos de resposta principais

Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

Etapa 3: Rastrear o status da transação

Após criar uma assinatura, monitore o ciclo de vida dela 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

A API do Localpayment fornece vários códigos de status para indicar o estado da assinatura.
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 assinatura bem-sucedida: fluxo padrão de assinatura com cartão válido.
  2. Assinatura de plano fixo: assinatura com plano predefinido.
  3. Assinatura personalizada: assinatura com parâmetros de cobrança personalizados.
  4. Erros de validação: cartão inválido, campos obrigatórios ausentes
  5. Atualizações de status: gerenciamento de webhooks e consulta de status

Próximos passos

Após a criação de uma assinatura, você poderá precisar realizar ações adicionais, como:

Atualizar assinatura

Modifique os detalhes de uma assinatura existente, incluindo valor da cobrança, frequência ou informações do cliente.

Cancelar assinatura

Encerre assinaturas ativas preservando o histórico de transações e os registros de faturamento.

Tratar webhooks de assinatura

Configure webhooks para receber notificações em tempo real sobre eventos de assinatura e mudanças no status dos pagamentos.
Última modificação em 10 de novembro de 2026