Pular para o conteúdo principal
A Localpayment permite que os comerciantes processem pagamentos únicos usando cartões de crédito e débito, em vários países e moedas. Este guia descreve o processo para iniciar um pagamento único com cartão através da API da Localpayment, detalhando os parâmetros necessários, o tratamento de respostas e a interpretação dos códigos de status.

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ção POST 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 usando curl:
curl
Veja todos os parâmetros disponíveis na solicitação.

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:
  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 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.
Última modificação em 20 de novembro de 2026