Boas Práticas Operacionais
Uma operação confiável começa antes da primeira transação. As configurações dos provedores, dos fluxos de pagamento e das notificações devem ser revisadas, testadas e monitoradas continuamente.
Este guia reúne recomendações para operadores da plataforma e equipes de integração. Para obter instruções detalhadas, consulte os guias indicados em cada etapa.
Prepare a operação
Antes de configurar a plataforma:
- defina quem poderá administrar usuários, PSPs, fluxos e integrações;
- conceda somente os acessos necessários para cada função;
- mantenha as credenciais e as Chaves Secretas em um gerenciador de segredos;
- separe as configurações, as credenciais, os dados e as URLs dos ambientes de homologação e produção;
- identifique os países, as moedas e os meios de pagamento que serão utilizados;
- confirme com cada PSP os serviços contratados e as credenciais disponíveis.
Não compartilhe credenciais por email ou aplicativos de mensagens, não as armazene no código-fonte e não registre tokens, dados pessoais ou dados de cartão em logs.
Siga a sequência de configuração
Siga esta ordem para evitar dependências incompletas:
- Cadastre e revise os provedores em PSPs, conforme o guia de cadastro de PSP;
- Configure as credenciais, os países, os meios de pagamento e as taxas;
- Crie o roteamento em Fluxo de pagamento, seguindo o guia de fluxo de pagamento;
- Revise todos os caminhos e ative um fluxo para cada meio de pagamento;
- Em Integração, proteja a Chave Secreta e configure a URL descrita no guia de notificações;
- Realize transações de teste e confirme tanto as respostas quanto as notificações.
Use Visualizar para consultar um fluxo sem o risco de alterá-lo. Antes de salvar uma edição, confirme o merchant e o meio de pagamento selecionados.
Somente um fluxo pode permanecer ativo para cada meio de pagamento. Sem um fluxo ativo, as transações desse meio não são processadas.
Valide os dados antes de salvar
| Área | O que deve ser revisado |
|---|---|
| PSP | Provedor contratado e ativo, credenciais válidas e países atendidos |
| Taxas | Percentuais, valores fixos, valores mínimos, moedas e PayOut |
| Fluxo | Nome descritivo, saídas Sim e Não, percentuais do balanceador totalizando 100% e um PSP ao final de cada caminho |
| Pagamento | Merchant, valor, moeda, país, meio de pagamento e campos obrigatórios |
| Integração | URL pública, HTTPS, resposta 2xx, validação do checksum e idempotência |
Não presuma que um PSP recém-cadastrado já esteja apto a receber pagamentos. Ele deve estar configurado e fazer parte do fluxo ativo correspondente.
Para pagamentos com cartão, utilize somente os componentes aprovados e consulte o guia de processamento de pagamentos PCI e Não-PCI. Nunca utilize cartões reais em ambientes de teste.
Aplique alterações com segurança
- Registre o objetivo, o responsável e a janela da alteração;
- Revise o estado atual antes de iniciar a edição;
- Sempre que possível, prepare e valide um fluxo inativo;
- Confirme todos os caminhos, os provedores e as credenciais;
- Ative a alteração durante o período planejado;
- Realize uma transação de teste para cada meio de pagamento afetado;
- Confirme o resultado inicial e o recebimento da notificação;
- Monitore as transações seguintes e mantenha um plano de reversão.
Alterar ou desativar um fluxo ativo afeta as transações seguintes. Não realize alterações sem confirmar que outro fluxo válido poderá ser ativado em caso de falha.
Monitore a operação
Monitore continuamente:
- o volume e os estados das transações por meio de pagamento;
- o aumento de recusas ou falhas técnicas por PSP;
- o tempo de resposta e a indisponibilidade dos provedores;
- as tentativas realizadas por meio de provedores alternativos;
- os erros HTTP, a latência e a indisponibilidade dos webhooks;
- as notificações duplicadas, atrasadas ou ainda não processadas;
- a validade das credenciais, dos contratos e dos certificados HTTPS.
A resposta inicial de um pagamento nem sempre é definitiva. Atualize os pedidos somente após validar a resposta ou a notificação e processe os eventos de forma idempotente.
Previna e corrija erros comuns
| Sintoma | Causa provável | Ação recomendada |
|---|---|---|
| O pagamento não é processado | Não há um fluxo ativo para o meio de pagamento | Revise a aba correspondente e ative um fluxo válido |
| O PSP não aparece no fluxo | O cadastro, as credenciais, as taxas ou a compatibilidade estão incompletos | Revise o país, a moeda e o meio de pagamento contratados |
| O fluxo não pode ser salvo | Há uma saída sem ligação, um caminho sem PSP ou percentuais que não totalizam 100% | Complete todos os caminhos e ajuste os percentuais |
| O PSP rejeita a configuração | A credencial é inválida ou o serviço não está habilitado | Valide os dados com o PSP sem expô-los em chamados |
| O pagamento é encaminhado ao PSP incorreto | As condições ou a prioridade não correspondem à regra esperada | Visualize cada caminho e teste os valores-limite |
| A atualização não é recebida | A URL está ausente, inacessível ou retornando um erro | Teste o endpoint, o HTTPS e a resposta 2xx |
| Uma atualização é aplicada mais de uma vez | O consumidor não é idempotente | Controle os eventos por meio dos identificadores recebidos |
| Um pagamento com token falha antes de chegar ao PSP | O token é inválido, foi removido ou não possui uma associação válida | Solicite outro token ou realize uma nova captura segura |
Ao investigar uma falha, utilize os identificadores da transação e do evento. Não copie Chaves Secretas, credenciais, PANs ou códigos de segurança para chamados, logs ou ferramentas de suporte.
Checklists operacionais
Antes de uma alteração
- Confirmei o merchant, o ambiente e o meio de pagamento;
- Revisei os PSPs, as credenciais, as taxas e a compatibilidade;
- Validei todos os caminhos e provedores alternativos do fluxo;
- Preparei os testes e um plano de reversão;
- Comuniquei a janela e o responsável pela alteração.
Após uma alteração
- Confirmei qual fluxo está ativo;
- Realizei transações de teste representativas;
- Verifiquei o PSP selecionado e o estado retornado;
- Confirmei o recebimento e a validação da notificação;
- Monitorei falhas, recusas e latência após a ativação.
Durante a operação
- Investiguei variações anormais de volume ou estado;
- Verifiquei falhas de PSPs e webhooks;
- Confirmei que cada notificação foi processada uma única vez;
- Revisei os acessos e removi as permissões desnecessárias;
- Mantive as credenciais, os contratos e os certificados atualizados.