Pular para o conteúdo principal
Atraia mais clientes permitindo que dividam as compras em pagamentos mensais. Saiba como implementar e gerenciar facilmente planos de parcelamento para aumentar a conversão e o valor médio dos pedidos. A Localpayment permite que os comerciantes ofereçam planos de parcelamento, para que os clientes dividam suas compras em vários pagamentos mensais. Este guia descreve o processo de criação de planos de parcelamento por meio da API da Localpayment, detalhando os parâmetros obrigatórios, o tratamento das respostas e o gerenciamento de todo o ciclo de vida do parcelamento.

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.

Etapa 1: Criar o orçamento do plano de parcelamento

Antes de processar um pagamento parcelado, você precisa gerar um orçamento do plano de parcelamento para apresentar as opções de pagamento ao cliente. Para solicitar o orçamento de um plano de parcelamento, você precisará enviar uma solicitação POST para o endpoint Gerar orçamento de parcelamento.

Parâmetros-chave da solicitação

As parcelas estão disponíveis somente em moeda local. No Peru, você pode oferecer parcelamento em pagamentos em PEN, mas não em pagamentos em USD.

Exemplo de solicitação

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

Etapa 2: Lidar com a resposta do orçamento

Resposta bem-sucedida

Um orçamento de parcelamento bem-sucedido inclui informações detalhadas do plano de pagamento:

Campos de resposta principais

Resposta de erro

Quando a geração do orçamento de parcelamento falha::

Melhores práticas para apresentação de parcelamentos

  • Exiba todos os custos com clareza (taxas de financiamento, valor total)
  • Mostre os valores das parcelas mensais em destaque
  • Inclua uma comparação entre as diferentes opções de parcelamento
  • Explique o processo de pagamento automático das parcelas futuras
  • Inclua informações de suporte ao cliente
  • Trate a expiração do token com elegância (janela de 10 minutos)

Etapa 3: Processar o pagamento parcelado

Depois que o cliente selecionar um plano de parcelamento, processe o pagamento usando o token de parcelamento.

Exemplo de solicitação

curl

Etapa 4: Acompanhar o status do parcelamento

Acompanhe o progresso do plano de parcelamento por meio destes métodos:

Webhooks (Recomendado)

Receba notificações em tempo real para cada pagamento parcelado e para as mudanças de status do plano.

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 monitorar os planos de parcelamento e o desempenho dos pagamentos.

Códigos de status comuns

A API da Localpayment fornece vários códigos de status para planos de parcelamento e pagamentos.
APPROVED não é o status final. Significa que o pagamento com cartão foi confirmado, mas os fundos ainda não foram creditados no seu saldo. Você pode ver o pagamento, mas não pode sacar os fundos até que o status mude para Completed. Isso costuma levar de 1 a 2 dias, dependendo do provedor.
Referência completaConsulte todos os códigos de status em nossa Documentação de Status da Transação.

Etapa 5: Gerenciar o ciclo de vida do parcelamento

Fluxo de pagamento parcelado


Testando sua integração

Cenários de teste

Verifique se sua integração lida com esses cenários:
  1. Parcelamento bem-sucedido: fluxo completo de pagamento parcelado
  2. Várias opções de plano: apresente diferentes prazos de parcelamento (2, 3, 6 meses)
  3. Expiração do token: trate o installmentsToken expirado (janela de 10 minutos)
  4. Atualizações de status: gerenciamento de webhooks e consulta de status.

Próximos passos

Após implementar o parcelamento, considere estes recursos adicionais::

Reembolsar a transação

Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação para obter detalhes.

Analisar detalhes da transação

Você pode obter informações detalhadas sobre as transações usando a API Localpayment.

Última modificação em 20 de novembro de 2026