Pular para o conteúdo principal
A pré-autorização é um processo em duas etapas que permite aos comerciantes verificar o método de pagamento de um cliente antes de concluir uma transação. Esse processo retém temporariamente o valor da transação na conta do cliente, sem debitá-lo efetivamente. Na primeira etapa, é feita uma solicitação de pré-autorização, reservando o valor especificado. Isso garante que o cliente tenha fundos suficientes e que o método de pagamento seja válido. No entanto, os fundos não são transferidos para o comerciante nesta fase. Na segunda etapa, a solicitação de captura é executada para finalizar o pagamento. O valor pré-autorizado é então debitado da conta do cliente e creditado ao comerciante.

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: Solicitar uma pré-autorização

Para iniciar uma pré-autorização, você precisará enviar uma solicitação POST para o endpoint Criar Payin e definir o header x-capture como true.

Parâmetros-chave da solicitação

A solicitação requer vários objetos-chave: O paymentMethod.code depende do país, da bandeira do cartão e do produto (crédito ou débito). No Peru, ele também depende da moeda. Consulte os Códigos de métodos de pagamento com cartão para ver a lista completa.

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 transação e identificadores de rastreamento.

Campos de resposta principais

Resposta de erro

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

Etapa 3: Capturar os fundos

Após pré-autorizar uma transação, você deve capturar os fundos para debitar a conta do cliente. Certifique-se de que a solicitação de captura seja para o valor total da pré-autorização. A retenção da pré-autorização sobre os fundos expirará após 7 dias. Se você não capturar os fundos dentro desse período, eles serão liberados automaticamente para o cartão do cliente. Para capturar uma pré-autorização, envie uma solicitação PATCH para o endpoint Capturar Payin autorizado.

Exemplo de solicitação

curl

Resposta bem-sucedida


Liberar fundos não utilizados

Para garantir uma experiência positiva para o cliente, recomenda-se liberar quaisquer fundos pré-autorizados que não serão utilizados. Ao iniciar a liberação por meio de uma solicitação de API, você evita que seus clientes esperem os 7 dias completos para a liberação automática. Para liberar fundos não utilizados, envie uma solicitação PATCH para o endpoint Cancelar autorização de Payin.

Exemplo de solicitação

curl

Resposta bem-sucedida


Etapa 4: Rastrear o status da transação

Após iniciar um pagamento pré-autorizado, acompanhe seu andamento 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 Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.
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.
Para obter informações completas sobre os códigos de status, consulte a 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. Transação concluída com sucesso: Fluxo padrão de Payin
  2. Erros de validação: conta bancária inválida, campos ausentes
  3. Atrasos no processamento: transações que levam tempo para serem processadas.
  4. Transações com falha: Fundos insuficientes, beneficiários bloqueados
  5. Atualizações de status: gerenciamento de webhooks e consulta de status.

Próximos passos

Após o processamento da pré-autorização, você poderá precisar realizar ações adicionais, como:

Reembolsar a transação

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

Gerenciar estornos

Em caso de disputa, você poderá precisar lidar com estornos. Consulte a documentação sobre estornos para obter informações sobre esse processo.

Analisar detalhes da transação

Recupere informações de transações usando a API Localpayment. Consulte a documentação de Informações de Transação para obter detalhes.

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