> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testando

Guia completo para testes de integração. Dados de teste, cenários e lista de verificação de validação.

Teste minuciosamente a sua integração com o Localpayment antes de a colocar em funcionamento. Este guia completo fornece dados de teste, cenários e procedimentos de validação para garantir que a sua implementação funcione corretamente em todos os métodos de pagamento e casos extremos.

## Pré-requisitos

Antes de iniciar os testes, certifique-se de que as seguintes configurações estejam corretas:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Ambiente de Sandbox

O ambiente de teste é uma réplica completa do nosso sistema de produção, projetado especificamente para testes:

> [card] Processamento realista
>
> Simula fluxos e prazos de pagamento reais.

> [card] Sem dinheiro de verdade
>
> Todas as transações utilizam dados de teste.

> [card] Conjunto completo de recursos
>
> Todos os métodos e operações de pagamento estão disponíveis.

> [card] Testes isolados
>
> Os dados do seu ambiente de teste são mantidos separados dos dados de produção.

***

## Dados de teste

### Pagamentos com cartão

Teste pagamentos com cartão de crédito e débito em diversos cenários:

| Número do cartão | Cenário | Resultado esperado | Objetivo do teste |
| - | - | - | - |
| 4242424242424242 | ✅ Pagamento realizado com sucesso | Aprovação imediata | Fluxo de pagamento básico |
| 4000000000000002 | ❌ Cartão recusado | Recuse com justificativa. | Manuseio de recusa |
| 4000002500003155 | 🔐 Necessário 3D Secure | Redirecionamento de autenticação | Fluxo 3D Secure |
| 4000000000009995 | ⚠️ Erro de processamento | Falha temporária | Verificações de saldo |

**Detalhes do cartão padrão:**

* **Data de validade**: Qualquer data futura (ex.: 12/2029)
* **CVC**: Qualquer número de 3 dígitos (ex.: 123) para cartões Mastercard e Visa ou qualquer número de 4 dígitos (ex.: 1234) para cartões American Express.
* **Nome do titular do cartão**: Qualquer nome de teste (ex.: "John Doe")

***

## Teste de Cenários de Erro

### Erros de validação

* Omitir campos obrigatórios (paymentMethod, amount)
* Usar formatos inválidos (moeda incorreta, números de documentos inválidos)
* Testar restrições de parâmetros (limites de valor, restrições de país)

### Testes de autenticação

* Utilizar tokens de acesso expirados
* Teste com credenciais inválidas
* Verifique as restrições da lista branca de IPs

***

## Teste de Webhook

Certifique-se de que seu endpoint de webhook esteja lidando corretamente com as notificações:

### Configuração do endpoint

* Verificar requisito HTTPS
* Teste de verificação de assinatura
* Confirme imediatamente a resposta 200 OK.

### Processamento de eventos

* Teste todos os tipos de eventos (payins, payouts, virtual accounts)
* Verificar o tratamento da idempotência
* Confirme o processamento assíncrono.

### Tratamento de erros

* Teste cenários de tempo limite
* Verificar lógica de repetição
* Monitorar falhas de entrega

***

## Simulação de Virtual Account (Estágio)

Para integrações de Virtual Account, a Localpayment fornece um endpoint de simulação dedicado para testar todo o ciclo de vida (Criação -> Financiamento -> Notificação).

### Pagamentos em Virtual Account (Simulação)

Para simular um pagamento bem-sucedido no ambiente Stage, utilize os mesmos dados do beneficiário (nome, tipo de documento e ID do documento) fornecidos na criação da Virtual Account. Não são necessárias identidades de teste separadas; o endpoint [Simulate a Virtual Account Payment](https://docs.localpayment.com/pt-br/reference/simulate-payin-to-virtual-account.md) validará os dados do pagador em relação às informações registradas durante a criação da conta.

### Cenários de teste principais:

| Cenário | Objetivo | Exigência |
| :- | :- | :- |
| **Verificar status** | Confirme a ativação da conta. | Verifique [Get Virtual Account Status](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) após a criação. |
| **Simular Pay-In** | Acione um pagamento simulado | Utilize [Simular um Pagamento com Virtual Account](https://docs.localpayment.com/pt-br/reference/simulate-payin-to-virtual-account.md) com os mesmos dados do beneficiário utilizados na criação da conta. |
| **Entrega via Webhook** | Validar a lógica do ouvinte | Certifique-se de que `payin.completed` (status: `COMPLETED`) seja recebido após a simulação. |

> [!NOTE]
>
> **Importante**
>
> * **Mapeamento de campos**: Na chamada de simulação, use o `beneficiary.bank.account.number` retornado por [Get Virtual Account Status](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) para identificar a conta de destino. O `externalId` na requisição de simulação deve ser um identificador único da transação de payin — use um valor diferente para cada requisição. Inclua também o seu **accountNumber** (Merchant ID) real para identificar o projeto.
> * **Identidades**: utilize os mesmos dados do beneficiário (nome, tipo de documento e ID) fornecidos ao criar a Virtual Account. Consulte o [Guia de Simulação Completo](https://docs.localpayment.com/pt-br/docs/simulate-virtual-account-payment.md) para obter detalhes.

***

## Lista de verificação de validação

Antes de iniciar a produção, verifique:

* **Fluxos de pagamento**: Confirme se todos os métodos de pagamento funcionam corretamente, incluindo cenários de sucesso e de erro.
* **Tratamento de Webhooks**: Garantir que todos os eventos de webhook sejam recebidos, verificados e processados conforme o esperado.
* **Tratamento de erros**: Exibir mensagens de erro claras para os usuários e implementar a lógica de repetição adequada quando necessário.
* **Segurança**: Imponha o uso de HTTPS, verifique as assinaturas e assegure que todos os dados sensíveis sejam tratados com segurança.
* **Experiência do usuário**: Forneça estados de carregamento claros, mensagens úteis e fluxos de redirecionamento suaves ao longo de toda a jornada de pagamento.

***

## Ferramentas de teste

Baixe nossa coleção completa do Postman com cenários de teste pré-configurados:

> [card] [Coleção do Postman](https://docs.localpayment.com/pt-br/reference/postman-collection.md)
>
> Obtenha a coleção completa de testes com modelos de ambiente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.