Integrar meios de pagamento: o que está realmente envolvido
Integrar um fornecedor de pagamentos não é tecnicamente difícil — os serviços modernos têm boa documentação e exemplos funcionais. O que torna isto complicado é tudo o que está fora do caminho feliz: pagamentos falhados, devoluções, estornos, encomendas duplicadas, e o que acontece quando o cliente fecha o separador a meio.
Este guia cobre a integração e, com mais detalhe, os casos limite onde o dinheiro se perde de verdade.
Escolher os meios que o seu mercado usa#
As preferências de pagamento são fortemente regionais. Oferecer os meios errados perde vendas no pagamento, que é o sítio mais caro para perder alguém.
| Meio | Onde conta | A ter em atenção |
|---|---|---|
| MB Way | Essencial em Portugal | Confirmação imediata, muito usado |
| Referência multibanco | Muito usado em Portugal | Confirmação diferida; encomendas ficam pendentes |
| Cartão | Internacional e empresarial | Custo maior, risco de estorno |
| PayPal | Internacional, marca reconhecida | Custo maior, processo de disputa próprio |
| Apple Pay e Google Pay | Móvel, aumenta conversão | Exige HTTPS e verificação de domínio |
| Pagamento a prazo | Cresce em vários mercados | O fornecedor assume o risco, por uma percentagem |
| Transferência SEPA | B2B e valores altos | Confirmação lenta; encomendas ficam à espera |
Comece com dois ou três meios que o seu mercado use mesmo. Cada meio adicional é mais uma escolha no pagamento e, subtilmente, mais um percurso para testar depois de cada atualização.
Como funciona a integração#
A forma é a mesma em praticamente todos os fornecedores modernos, e vale a pena percebê-la porque os modos de falha decorrem dela.
- O seu servidor cria uma intenção de pagamento com valor, moeda e referência da encomenda.
- O cliente é enviado para a página do fornecedor, ou preenche um formulário incorporado.
- O cliente autoriza junto do banco ou emissor, frequentemente com autenticação forte.
- O fornecedor devolve o cliente ao seu URL de retorno — que nunca deve usar como prova de pagamento.
- O fornecedor envia um webhook ao seu servidor com o estado definitivo. É esta a verdade.
- O seu servidor verifica a assinatura do webhook, atualiza a encomenda e envia a confirmação.
- Os dados do cartão nunca tocam no seu servidor — o que o mantém fora da parte pesada do PCI.
Os passos quatro e cinco concentram a maioria dos erros. O cliente pode fechar o navegador antes de regressar; o webhook chega na mesma. Construa sobre o webhook, não sobre o retorno.
Os casos limite onde se perde dinheiro#
Não aparecem em testes e aparecem na primeira semana de movimento a sério.
| Situação | O que corre mal | Tratamento |
|---|---|---|
| Webhook chega duas vezes | Encomenda processada em duplicado | Idempotência: processar cada evento uma vez |
| Webhook chega antes do retorno | Corrida que sobrescreve o estado | Transições de estado explícitas, sem retroceder |
| Cliente fecha o separador após pagar | Pago, sem encomenda | Criar a encomenda no webhook, não no retorno |
| Pagamento falha após reservar stock | Stock preso sem venda | Expirar a reserva após um período fixo |
| Devolução parcial | Contabilidade deixa de bater certo | Modelar devoluções como evento de primeira classe |
| Estorno | Dinheiro perdido, produto enviado | Guardar provas; regras de risco em valores altos |
| Fornecedor indisponível | Zero vendas, não menos vendas | Um segundo meio como alternativa |
Conformidade e testes#
Uma lista curta que cobre o que fica caro quando falta.
- Use campos alojados ou redirecionamento para que os dados de cartão nunca toquem no seu servidor — reduz enormemente o âmbito PCI.
- A autenticação forte é obrigatória na Europa; teste o percurso com um cartão que a exija.
- Verifique a assinatura de cada webhook. Um webhook não verificado é um endpoint público que consegue marcar encomendas como pagas.
- Mostre preços com IVA incluído a consumidores e torne os portes visíveis antes do último passo.
- Guarde dados de encomenda e pagamento pelo prazo fiscal exigido, e não mais do que o necessário quanto a dados pessoais.
- Teste devoluções e devoluções parciais antes do lançamento, não quando o primeiro cliente pedir.
- Faça uma transação real em produção com um cartão real e devolva-a a si próprio. O modo de teste não cobre tudo.
Perguntas frequentes
Que fornecedor de pagamentos devo escolher?
Escolha pelos meios que suporta no seu mercado, pelas comissões ao seu volume, e por quão bem integra com a sua plataforma. Para uma loja portuguesa, o suporte a MB Way e referência multibanco é o primeiro filtro. As diferenças de preço entre os grandes fornecedores são pequenas o suficiente, com volume modesto, para não serem decisivas.
Preciso de conformidade PCI?
Sim, mas o âmbito depende inteiramente de como integra. Se usar campos de pagamento alojados ou redirecionamento, de modo que os dados de cartão nunca toquem no seu servidor, a sua obrigação reduz-se à autoavaliação mais simples. Se processar dados de cartão diretamente, entra num regime completamente diferente — praticamente nenhuma loja o deve fazer.
Porque preciso de webhooks se existe URL de retorno?
Porque o retorno depende do navegador do cliente. Se fechar o separador, perder ligação, ou ficar preso na página do banco, o retorno nunca acontece — mas o dinheiro foi debitado na mesma. O webhook vem do servidor do fornecedor e chega de qualquer maneira. Construa a encomenda no webhook e use o retorno apenas para mostrar algo ao cliente.
Como evito encomendas duplicadas?
Torne o processamento de webhooks idempotente: guarde o identificador de cada evento processado e ignore repetições. Os fornecedores reenviam webhooks quando não recebem confirmação, por isso entregas duplicadas são comportamento normal e não avaria. Sem esta verificação, envia dois e-mails de confirmação e desconta stock duas vezes.
integrar pagamentosmb way loja onlinegateway de pagamentowebhook pagamentoconformidade pcipagamentos online
