Antes de começar
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 um pagamento com cartão
Para iniciar um pagamento único com cartão, você precisará enviar uma solicitaçãoPOST para o endpoint Criar Payin.
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
Pagamento com cartão tokenizado
Se você já tiver tokenizado o cartão de um cliente, poderá usar o token em vez de enviar os dados completos do cartão para processar um pagamento único. Isso aumenta a segurança e simplifica o fluxo de pagamento, eliminando a necessidade de solicitar novamente as informações do cartão. Para obter informações detalhadas sobre a tokenização de cartões, consulte a documentação de Tokenização.Pagamento com 3D Secure
Se o titular do cartão exigir autenticação adicional, o fluxo prosseguirá pelo 3D Secure. Nesse caso, o Localpayment retorna o URL de desafio do emissor na resposta da API, e é responsabilidade do comerciante redirecionar o cliente ou exibir o desafio durante o processo de finalização da compra. Isso permite que o titular do cartão conclua a verificação necessária. A experiência exata com o 3D Secure pode variar dependendo do emissor e do país do cliente. Para obter informações detalhadas sobre pagamentos 3D Secure, consulte a documentação do 3D Secure.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: Rastrear o status da transação
Após iniciar um pagamento único, monitore seu progresso através 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.
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:- 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 de um pagamento único, 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 para obter detalhes.
Gerenciar estornos
Em caso de disputa, você poderá precisar lidar com estornos. Consulte a documentação para obter informações sobre esse processo.
Analisar detalhes da transação
Você pode obter informações detalhadas sobre as transações usando a API Localpayment.

