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çãoPOST 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 usandocurl:
curl
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çãoPATCH 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çãoPATCH 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:- Transação concluída com sucesso: Fluxo padrão de Payin
- Erros de validação: conta bancária inválida, campos ausentes
- Atrasos no processamento: transações que levam tempo para serem processadas.
- Transações com falha: Fundos insuficientes, beneficiários bloqueados
- 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.

