Category: E-commerce

Integrar um gateway de pagamento ao PrestaShop pode parecer simples no papel.

O gateway fornece documentação da API, credenciais de sandbox, chaves de autenticação, URLs de retorno de chamada e alguns endpoints. O módulo PrestaShop então envia a solicitação de pagamento, recebe a resposta, cria o pedido e redireciona o cliente para a página de confirmação.

Numa loja PrestaShop real, porém, o sistema de pagamento raramente funciona sozinho.

No momento em que uma loja utiliza um módulo de finalização de compra em uma única página (OPC), como o SuperCheckout, vários módulos de pagamento, fluxos de pagamento personalizados, iframes, métodos de pagamento baseados em JavaScript e outras personalizações de finalização de compra podem interagir entre si.

É aqui que muitas integrações de pagamento se tornam difíceis.

Durante o trabalho de compatibilidade com gateways de pagamento, encontramos casos em que um método de pagamento funcionava perfeitamente no checkout padrão do PrestaShop, mas se comportava de maneira diferente no OPC. Por exemplo, um provedor de pagamento podia ser exibido corretamente no checkout padrão, enquanto opções como BLIK, seleção de banco ou BNPL (Buy Now, Pay Later – Compre Agora, Pague Depois) desapareciam no SuperCheckout.

A lição importante foi que integrar um gateway de pagamento não se resume apenas a fazer a chamada da API funcionar. Trata-se de garantir que todo o ciclo de pagamento funcione corretamente dentro do checkout do PrestaShop.

1.0 O que um gateway de pagamento personalizado realmente precisa?

Em linhas gerais, uma integração de pagamento no PrestaShop precisa lidar com cinco aspectos:

1. Exibir o método de pagamento na finalização da compra.
2. Enviar os dados do cliente ou de pagamento para o gateway.
3. Receber e validar a resposta do gateway.
4. Crie ou atualize o pedido do PrestaShop corretamente.
5. Redirecione o cliente para a página de confirmação ou de erro apropriada.

Um módulo de pagamento típico estende a classe base.

O módulo de pagamento normalmente funciona com hooks como:

O gancho é responsável por disponibilizar o método de pagamento para o checkout.

O gancho controla o que o cliente vê após retornar do processo de pagamento.

Por exemplo:

public function hookPaymentOptions($params) { if (!$this->active || !$this->checkCurrency($params['cart'])) { return []; } $paymentOption = new PaymentOption(); $paymentOption ->setCallToActionText($this->l('Pagar com Cartão')) ->setAction( $this->context->link->getModuleLink( $this->name, 'redirect', [], true ) ); return [$paymentOption]; }

O ponto importante é que esse gancho não deve simplesmente presumir que o método de pagamento sempre poderá ser exibido.

Moeda, país, operadora, estado do cliente, valor do carrinho, configuração do módulo e disponibilidade do gateway podem influenciar se o método de pagamento deve ser exibido.

2.0 A peça que muda tudo: OPC

O checkout padrão do PrestaShop e um módulo OPC não processam necessariamente os métodos de pagamento exatamente da mesma maneira.

Essa foi uma das lições mais importantes aprendidas ao trabalhar com vários módulos de pagamento.

Com o checkout padrão, um módulo de pagamento geralmente controla a renderização de suas próprias opções de pagamento e o fluxo de pagamento.

Com um OPC, o módulo de finalização de compra torna-se mais uma camada entre o módulo de pagamento e o cliente. Isso significa que os seguintes elementos podem interagir:

O cliente
↓
OPC / SuperCheckout
↓
Opções de pagamento
↓
Módulo de pagamento
↓
API de Gateway
↓
Resposta do gateway
↓
Módulo de pagamento
↓
OPC / PrestaShop
↓
A confirmação da ordem

Um módulo de pagamento pode, portanto, estar completamente correto do ponto de vista da API e ainda assim não se comportar corretamente dentro de um OPC.

É por isso que os testes de compatibilidade de pagamento devem sempre incluir ambos:

• Checkout padrão do PrestaShop
• O OPC real usado pela loja

Testar apenas o checkout padrão pode dar a falsa impressão de que a integração está completa.

3.0 Um exemplo do mundo real: Opções PayU ausentes dentro do OPC

Um dos problemas práticos que encontramos envolveu as opções de pagamento do PayU.

Na página de finalização de compra padrão do PrestaShop, o PayU conseguiu exibir corretamente os métodos de pagamento disponíveis. No entanto, no SuperCheckout, algumas opções de pagamento estavam faltando.

Por exemplo, dependendo da configuração e do carrinho:

• BLIK não estava visível de forma consistente.
• A lista de seleção de bancos não foi expandida corretamente.
• Algumas linhas de BNPL/pagamento estavam faltando.
• Em alguns casos, BLIK aparecia e depois desaparecia.

À primeira vista, parecia ser um problema da API da PayU. Mas não era.

A etapa diagnóstica importante foi comparar o fluxo de pagamento entre o checkout padrão e o SuperCheckout.

Quando o mesmo módulo de pagamento funciona no checkout padrão, mas falha no OPC, a investigação deve ir além da API do gateway.

Precisamos verificar como o OPC constrói os métodos de pagamento e quais informações ele passa para os módulos de pagamento.

4.0 O valor do pagamento pode afetar a visibilidade do método de pagamento.

Um aspecto particularmente importante desta investigação foi o valor do carrinho de compras. Os sistemas de pagamento geralmente têm limites mínimos e máximos para transações. Por exemplo:

Pagamentos
↓
Confira o valor do carrinho
↓
Valor mínimo? Valor máximo?
↓
Elegível / Não elegível

Durante a investigação de compatibilidade com o PayU, rastreamos a lógica de filtragem do método de pagamento até o valor do carrinho sendo passado pelas verificações do método de pagamento.

O fluxo relevante envolvia o cálculo do carrinho de compras e a filtragem de métodos de pagamento do PrestaShop, incluindo a lógica relacionada a:

Carrinho::AMBOS

e:

PayMethodsCache::checkMinMax

Isso é importante porque uma opção de pagamento pode desaparecer do checkout sem que a própria API retorne um erro.

O gateway pode simplesmente ser considerado inelegível para o valor recebido pelo módulo de pagamento. Isso nos dá uma importante regra de depuração:

Se uma opção de pagamento desaparecer de um carrinho de compras, não presuma imediatamente que a API de pagamento está com problemas. Primeiro, verifique o valor do carrinho, a moeda, os limites mínimo e máximo e os valores que atendem aos critérios de elegibilidade do método de pagamento.

Isso se torna ainda mais importante quando descontos, custos de envio, impostos, vouchers ou cálculos personalizados de finalização de compra estão envolvidos.

5.0 Por que os métodos de pagamento funcionam no Checkout padrão, mas falham no SuperCheckout

Uma forma útil de investigar esses problemas é comparar os dois ambientes de checkout.

5.1 Finalização de compra padrão do PrestaShop

Carrinho
↓
Localizador de opções de pagamento
↓
Ganchos de opções de pagamento
↓
Módulos de pagamento
↓
Opções de pagamento

5.2 Verificação OPC

Carrinho
↓
SuperCheckout
↓
Métodos de pagamento
↓
Módulos de pagamento
↓
Processamento OPC adicional
↓
Interface de pagamento renderizada

O segundo fluxo possui partes móveis adicionais.

Portanto, ao depurar um problema de pagamento, não verificamos apenas: “O módulo de pagamento está funcionando?”

Nós verificamos: “O módulo de pagamento funciona quando sua saída é consumida e renderizada por esta implementação específica de finalização de compra?”

Essa distinção economizou uma quantidade considerável de tempo de depuração.

6.0 A opção de pagamento é apenas uma parte da integração.

A partir da versão 1.7 do PrestaShop, os módulos de pagamento geralmente utilizam a abordagem mais antiga de gancho de pagamento para gerar o HTML de pagamento.

Uma opção de pagamento pode conter informações como:

$paymentOption
->setCallToActionText(...)
->setAction(...)
->setInputs(...)
->setAdditionalInformation(...)

objetos em vez de diretamente

Diferentes gateways exigem diferentes combinações.

6.1 Gateway baseado em redirecionamento

O cliente clica no método de pagamento e é redirecionado para o gateway.

Finalizar Compra
↓
Opção de pagamento
↓
Controlador de módulo
↓
Gateway

6.2 Formulário de pagamento incorporado

Os campos de pagamento são exibidos diretamente na página de finalização da compra.

Finalizar Compra
↓
Opção de pagamento
↓
Formulário de cartão/pagamento
↓
API de Gateway

6.3 Pagamento baseado em iframe

A interface do gateway está integrada ao processo de finalização da compra.

Finalizar Compra
↓
Opção de pagamento
↓
Iframe
↓
Gateway

As duas últimas abordagens exigem atenção adicional, pois JavaScript, manipulação do DOM, carregamento de iframe e atualizações do OPC podem afetar a interface de pagamento.

7.0 JavaScript torna-se crucial com OPC

Essa é uma área que os guias genéricos de integração de pagamentos costumam ignorar.

Um OPC pode atualizar dinamicamente partes do processo de finalização da compra quando o cliente faz alterações:

• endereço de entrega
• país
• portador
• método de pagamento
• Informações de pagamento
• método de envio

Quando isso acontecer, o HTML relacionado ao pagamento poderá ser substituído.

Um evento JavaScript que funcionou durante o carregamento inicial da página pode, portanto, parar de funcionar após uma atualização AJAX.

Por exemplo:

Carregamento inicial do checkout
↓
JS de pagamento inicializado
↓
O cliente altera as informações de pagamento/envio.
↓
OPC atualiza seção de pagamentos
↓
DOM original substituído
↓
O JS de pagamento não está mais anexado.

Isso pode produzir sintomas confusos.

O método de pagamento pode aparecer inicialmente, mas clicar nele não faz nada. Um iframe pode desaparecer.

Uma lista de bancos pode parar de crescer.

Uma opção de pagamento pode aparecer e desaparecer após a alteração de outro campo no processo de finalização da compra.

Portanto, o trabalho de compatibilidade muitas vezes exige alterações não apenas no PHP, mas também no JavaScript do módulo de pagamento.

8.0 Um exemplo real: SimplyLease + SuperCheckout

Outro exemplo envolveu a integração do SimplyLease com o SuperCheckout. O problema não se limitava à API do gateway.

Algumas informações e elementos da calculadora do SimplyLease faziam parte da apresentação de finalização da compra/pagamento e precisavam funcionar corretamente dentro do fluxo do SuperCheckout.

As alterações de compatibilidade envolveram tanto os modelos de módulo quanto a integração do JavaScript no SuperCheckout. Os arquivos envolvidos incluíram:

modules/simplylease/views/templates/hook/payment_info.tpl modules/simplylease/views/templates/hook/product_calculator.tpl

modules/supercheckout/controllers/front/SupercheckoutCore.php modules/supercheckout/views/js/front/supercheckout.js
modules/supercheckout/views/js/front/simplylease_supercheckout.js

Este é um bom exemplo de por que a compatibilidade de pagamentos às vezes exige alterações fora do próprio módulo do gateway de pagamento.

O provedor de pagamento pode expor os dados corretos, mas o processo de finalização da compra ainda precisa:

1. Renderize.
2. Preserve-o durante as atualizações do checkout.
3. Inicialize o JavaScript necessário.
4. Mantenha as informações de pagamento sincronizadas com o carrinho atual.

9.0 Outro problema comum: Método de pagamento não aparece

Também encontramos casos em que um método de pagamento como o Comfino não aparecia no SuperCheckout, mesmo que o próprio módulo de pagamento estivesse instalado e configurado.

Esse tipo de problema deve ser investigado sistematicamente.

Verifica:

9.1 O módulo está ativo?

$this->ativo

9.2 A moeda é suportada?

$this->checkCurrency($params['cart'])

9.3 O país recebe apoio?

Algumas plataformas de pagamento restringem os métodos de pagamento com base no país do cliente.

9.4 O total do carrinho está dentro dos limites do gateway de pagamento?

Os valores mínimo e máximo de transação podem impedir que um método seja exibido.

9.5 A operadora é compatível?

Alguns módulos de pagamento restringem os métodos de pagamento por operadora.

9.6 O método é a filtragem OPC?

O módulo de pagamento pode retornar métodos válidos que são coletados, filtrados ou renderizados. Mas o OPC ainda pode modificar a forma de pagamento.

9.7 O JavaScript está ocultando ou substituindo o elemento?

Tecnicamente, um método de pagamento pode ser retornado pelo PHP, mas ainda assim não estar visível na página final de finalização da compra.

É por isso que as ferramentas de desenvolvedor do navegador são tão importantes quanto os logs do PHP ao depurar integrações de pagamento.

10.0 Ganchos aos quais realmente precisamos prestar atenção

Uma integração de pagamento personalizada não deve ser tratada como uma implementação de gancho único.

Os mecanismos exatos dependem da arquitetura do gateway e do processo de finalização da compra, mas alguns são especialmente importantes.

10.1 Opções de pagamento

Este é o principal meio de expor o método de pagamento ao processo de finalização da compra.

É responsável pela devolução. Opções de pagamento objetos.

As verificações típicas incluem:

se (!$this->ativo) { retornar [];
}
if (!$this->checkCurrency($params['cart'])) { return [];
}

Restrições adicionais específicas do gateway podem então ser aplicadas.

10.2 Devoluções de pagamento

Esta opção é utilizada após o cliente concluir ou retornar do fluxo de pagamento. Ela pode exibir:

• referência do pedido
• status do pagamento
• instruções de pagamento adicionais
• informações específicas do gateway

10.3 opçõesDePagamentoPresente

Essa funcionalidade torna-se particularmente interessante quando vários módulos de pagamento e um OPC estão envolvidos.

Ele opera com base nas opções de pagamento reunidas e pode ser útil quando o sistema de finalização de compra precisa inspecionar ou modificar todo o conjunto de opções de pagamento.

Isso é diferente de implementar as opções de pagamento de um único gateway. gancho.

A distinção é importante:

Opções de pagamento
↓
Cada módulo de pagamento contribui com sua opção.
opçõesDePagamentoPresentes
↓
As opções de pagamento reunidas podem ser processadas.

Ao depurar a compatibilidade com OPC, entender onde as opções de pagamento são coletadas e onde são apresentadas pode fazer toda a diferença entre encontrar o problema rapidamente e passar horas analisando o módulo do gateway.

11.0 Criação de Pedidos: Nunca Confie no Navegador

Assim que o pagamento é recebido pelo gateway, a próxima etapa crucial é a criação do pedido. O método mais importante do PrestaShop nesse processo é:

validarPedido()

Um exemplo simplificado é:

$this->module->validateOrder(
$cart->id, Configuration::get('PS_OS_PAYMENT'),
$valorPago,
$paymentMethod,
$mensagem, [],
nulo, falso,
$customer->secure_key
);

Existem três valores que merecem atenção especial:

11.1 ID do Carrinho

O carrinho deve pertencer ao cliente/sessão esperado e deve ser válido.

11.2 Valor do pagamento

Não utilize indiscriminadamente:

$cart->getOrderTotal()

como comprovante de que o gateway recebeu esse valor.

O valor deve ser validado em relação à resposta do gateway.

11.3 Chave segura

O cliente Deve estar corretamente associado ao fluxo do carrinho/pedido.

12.0 Os webhooks devem ser idempotentes.

Um gateway de pagamento pode enviar o mesmo webhook mais de uma vez. Por exemplo:

Gateway
↓
webhook
↓
Seu servidor
↓
Resposta 200

Caso a resposta seja perdida:

Gateway
↓
webhook
↓
Seu servidor
↓
Resposta perdida
↓
Tentativas de reentrada do gateway

Se a integração criar um pedido sempre que receber um webhook, pedidos duplicados se tornam possíveis. Portanto, o callback deve verificar se o carrinho já possui um pedido antes de criar outro. Conceitualmente:

se ($carrinho->PedidoExiste()) {
// Já processado
// Retorna resposta bem-sucedida
}

O manipulador de webhook deve ser projetado para processar notificações repetidas com segurança.

13.0 Pagamento Síncrono vs. Assíncrono

Nem todos os gateways de pagamento confirmam o pagamento imediatamente.

13.1 Síncrono

O gateway confirma a transação imediatamente.

O cliente
↓
Gateway
↓
Pagamento aprovado
↓
validarPedido()
↓
PS_OS_PAGAMENTO
↓
Confirmação

13.2 Assíncrono

O cliente poderá efetuar a devolução antes da chegada da confirmação final do pagamento.

O cliente
↓
Gateway
↓
Voltar para a loja
↓
Pedido pendente
↓
webhook
↓
Verificar pagamento
↓
Alterar estado do pedido
↓
Pagamento aceito

Para gateways assíncronos, usar um estado de pedido pendente dedicado costuma ser mais seguro do que marcar o pedido como pago imediatamente.

Assim que o webhook confirmar o pagamento:

$history = novo OrderHistory();
$history->id_order = (int) $order->id;
$history->changeIdOrderState( Configuration::get('PS_OS_PAYMENT'),
$order
);
$history->addWithemail(true);

Isso garante que a transição do estado do pedido passe pelo mecanismo de histórico de pedidos do PrestaShop, em vez de simplesmente alterar o valor no banco de dados.

14.0 Uma das técnicas de depuração mais úteis: comparar os fluxos de finalização da compra

Quando um método de pagamento funciona no checkout padrão, mas não no OPC, recomendamos comparar todo o fluxo.

Passo 1: Verificar PHP

É hookPaymentOptions() executado?

Etapa 2: Inspecione as opções retornadas

O módulo de pagamento realmente retorna um opção de pagamento?

Passo 3: Confira o carrinho

Comparar:

• total
• moeda
• cliente
• país
• portador
• descontos
• impostos
• Remessa

Passo 4: Verifique o navegador

Olhe para:

• Erros de JavaScript
• Elementos DOM ausentes
• Requisições AJAX
• solicitações falharam
• erros de iframe

Etapa 5: Verifique o OPC

Determine se o SuperCheckout é:

• filtrando a opção de pagamento
• substituindo seu HTML
• Atualizando a seção de pagamento
• Alterar o carrinho antes da execução do módulo de pagamento.

Etapa 6: Verifique o gateway

Somente após a confirmação do fluxo de caixa local é que a investigação deve prosseguir para:

• Autenticação de API
• carga útil de solicitação
• assinatura
• resposta
• webhooks
• registros do gateway

Essa abordagem em camadas é muito mais rápida do que começar sempre com a API do gateway.

15.0 Problemas comuns de integração de pagamentos que observamos

O trabalho de compatibilidade no mundo real geralmente expõe problemas que não são óbvios na documentação do gateway.

15.1 A opção de pagamento desapareceu.

Causas possíveis:

• moeda não suportada
• restrição do país
• Valor do carrinho acima dos limites do gateway
• restrição da operadora
• Filtragem OPC
• Configuração do módulo de pagamento
• JavaScript ocultando o método

15.2 BLIK ou outra opção de pagamento aparece e desaparece

Causas possíveis:

• Confira a atualização AJAX
• nova renderização da opção de pagamento
• Inicialização do JavaScript
• Total do carrinho em alteração
• A elegibilidade do gateway está sendo recalculada.

15.3 A lista de bancos não se expande

Investigar frequentemente:

• Erros de JavaScript
• elementos DOM substituídos dinamicamente
• manipuladores de eventos anexados antes da atualização do OPC
• Inicialização JavaScript do provedor de pagamento

15.4 O iframe desaparece

Investigar:

• atualizar finalização da compra
• Inicialização de iframe
• Substituição do DOM
• Execução de JavaScript após atualizações AJAX
  

15.5 O pagamento foi efetuado com sucesso, mas o pedido permanece pendente.

Verifica:

• URL do webhook
• entrega de webhook
• verificação de assinatura
• consulta de carrinho/pedido
• transição de estado de ordem
• autenticação de retorno de chamada

15.6 O método de pagamento funciona no checkout padrão, mas não no OPC.

Isso indica fortemente que o problema pode estar na interação entre o módulo de pagamento e o OPC, e não na própria API do gateway.

16.0 Requisitos de segurança para um módulo de pagamento

Os módulos de pagamento lidam com operações sensíveis, portanto a segurança não pode ser tratada como uma melhoria opcional. No mínimo:

• Validar assinaturas de retorno de chamada.
• Valide a relação entre o carrinho e o cliente.
• Usar HTTPS.
• Validar certificados TLS.
• Nunca confie apenas no status de pagamento fornecido pelo navegador.
• Nunca armazene informações brutas de cartões de crédito, a menos que a arquitetura e os requisitos de conformidade o permitam explicitamente.
• Não registre informações de pagamento confidenciais.
  

• Evite serializar() e desserializar() / para dados externos não confiáveis.

• Validar e converter os valores recebidos.
• Proteja endpoints AJAX e de retorno de chamada personalizados.
• Utilize tokens seguros quando apropriado.
• Tornar o processamento de webhooks idempotente.

Uma página de confirmação de pagamento não constitui comprovante de pagamento.

A resposta verificada do servidor do gateway é o que deve determinar se o pedido é considerado pago.

17.0 O que muda ao dar suporte a vários módulos de pagamento?

Outra lição aprendida com o trabalho de compatibilidade com OPC é que adicionar um segundo ou terceiro módulo de pagamento pode expor problemas que não eram visíveis quando existia apenas um método de pagamento.

Por exemplo:

PayPal PayU
Comfino
SimplyLease
transferência bancária

Todas podem contribuir com opções de pagamento para o mesmo checkout. Portanto, o checkout precisa lidar com diferentes:

• Estruturas HTML
• JavaScript
• Requisitos do iframe
• redirecionamentos
• Fluxos de API
• regras de elegibilidade
• valores mínimos/máximos
• retornos de chamada assíncronos

Uma alteração feita em um método de pagamento pode afetar acidentalmente outro. É por isso que as correções de compatibilidade de pagamento devem ter um escopo bem definido.

Por exemplo, em vez de alterar toda a lógica de processamento de opções de pagamento globalmente, identifique o método de pagamento específico e aplique o tratamento de compatibilidade apenas onde for necessário.

18.0 Os testes devem incluir cenários reais de carrinho de compras.

Testar um gateway de pagamento com um produto simples de €10 não é suficiente. Uma matriz de testes adequada deve incluir:

Cenário	O que verificar
Único produto	A opção de pagamento aparece.
Vários produtos	A quantia correta chega ao portão
Desconto	O valor final a pagar está correto.
Taxa de envio	O gateway recebe o total correto.
Tributário	O valor do gateway corresponde ao pedido.
Valor mínimo do gateway	O método aparece/desaparece corretamente
Valor máximo do gateway	O método aparece/desaparece corretamente
Moeda não suportada	O método está oculto
País não suportado	O método está oculto
Checkout padrão	O pagamento funciona
OPC	O pagamento funciona
Caixa para celular	A interface do usuário funciona
Falha no pagamento	Estado correto do pedido/pagamento
Pagamento bem sucedido	O pedido foi criado corretamente.
Tentativa de refazer o webhook	Não é permitido fazer pedidos duplicados.
Abandono do cliente	Nenhum pedido pago incorretamente
Tempo limite do gateway	Correção do tratamento de erros/pendências

Para integrações OPC, teste também as atualizações do checkout. Altere o:

• endereço
• portador
• país
• método de pagamento
• quantidade
• desconto

e verifique se as opções de pagamento permanecem corretas após cada atualização.

19.0 Uma abordagem prática de desenvolvimento

Com base nos problemas que geralmente surgem em integrações reais, uma ordem de desenvolvimento mais segura é:

19.1 Faça o gateway funcionar com o checkout padrão do PrestaShop

Primeiro, estabeleça que:

Opção de pagamento
↓
Solicitação de gateway
↓
Resposta do gateway
↓
validarPedido()
↓
Confirmação

funciona corretamente.

19.2 Adicionar processamento de callback/webhook

Não deixe a confirmação assíncrona para o final.

19.3 Adicionar tratamento adequado do estado do pedido

Teste:

• sucesso
• falha
• pendente
• tempo limite

19.4 Teste com cartuchos realistas

Utilize descontos, frete, impostos, diferentes moedas e totais variados.

19.5 Integrar com OPC

Somente após o fluxo básico do gateway estar estável você deve investigar a compatibilidade com o SuperCheckout.

19.6 Teste JavaScript e atualizações dinâmicas

Isso é particularmente importante para formulários de pagamento incorporados, iframes, interfaces BLIK/seleção de banco e outros componentes de pagamento interativos.

19.7 Teste todos os métodos de pagamento em conjunto

Um sistema de finalização de compra que suporta cinco métodos de pagamento precisa ser testado como um sistema, e não como cinco módulos isolados.

20.0 Devo criar um gateway personalizado ou usar um módulo existente?

Nem todos os gateways justificam uma integração personalizada. Um módulo personalizado faz sentido quando:

• A porta de entrada é regional ou de nicho.
• Não existe nenhum módulo PrestaShop com suporte.
• O gateway requer lógica de negócios personalizada.
• Você precisa de um fluxo de trabalho específico para assinaturas ou pagamentos.
• Você precisa de funcionalidades que os módulos existentes não conseguem fornecer.

Mas construir uma integração de pagamento também significa aceitar a responsabilidade pela manutenção. O PrestaShop muda.

Alterações no PHP. Alterações nas APIs do Gateway.

Os requisitos de segurança mudam. Os módulos de finalização da compra mudam.

E eventualmente o provedor de pagamentos altera algo que quebra uma integração que, de outra forma, seria estável.

Para gateways de pagamento convencionais, um módulo estabelecido e com manutenção regular pode, portanto, ser significativamente mais barato do que manter um código de pagamento personalizado por vários anos.

21.0 A Lição Mais Importante da Integração de Pagamentos do PrestaShop

A maior lição ao trabalhar com gateways de pagamento é que a API geralmente não é a parte mais difícil. Envio:

Solicitação de API → Resposta da API

Geralmente é simples.

A parte difícil é tudo o que a rodeia:

┌── Regras monetárias
─── Regras do país
─── Valor do carrinho
─── Restrições da operadora
─── OPC
─── JavaScript
─── Iframes
─── Atualizações AJAX
─── Webhooks
─── A ordem afirma
─── notificações duplicadas
↓
O cliente → Finalizar Compra → Módulo de Pagamento → Gateway
↓
Criação de pedido
↓
A confirmação da ordem

A integração de pagamentos só é bem-sucedida quando toda a cadeia se comporta de forma consistente.

É por isso também que um problema como “BLIK ausente” ou “a lista de bancos não abre” não deve ser tratado imediatamente como um problema da API do gateway.

A causa real pode ser o cálculo do total do carrinho, a verificação de elegibilidade do método de pagamento, a renderização OPC, a inicialização do JavaScript ou uma atualização AJAX que substitui a interface de pagamento.

22.0 Lista de verificação final para um gateway de pagamento personalizado do PrestaShop

Antes de considerar a integração concluída, verifique:

• O módulo de pagamento é ampliado. Módulo de Pagamento.
• Opções de pagamento está implementado corretamente.
• retorno do pagamento É implementado onde necessário.
• Opções de pagamento utilizadas Opções de pagamento.
• As restrições cambiais foram verificadas.
• As restrições de país e de companhia aérea são verificadas quando aplicáveis.
• Os totais do carrinho foram validados.
• As respostas do gateway são verificadas.
• As assinaturas de retorno de chamada são validadas.
  
• ValidarPedido() A chamada é feita somente após a verificação bem-sucedida do pagamento.
• O valor utilizado no pedido é validado em relação à resposta do gateway.
• Os webhooks são idempotentes.
• Notificações duplicadas não criam pedidos duplicados.
• Os estados de ordem corretos são utilizados.
• Pagamentos falhados e pagamentos pendentes são tratados separadamente.
• Dados de pagamento sensíveis nunca são registrados ou armazenados desnecessariamente.
• O HTTPS é obrigatório.
• O checkout padrão do PrestaShop foi testado.
• O OPC foi testado separadamente.
• O JavaScript foi testado após atualizações da página de finalização de compra via AJAX.
• Os iframes e os elementos de pagamento interativos foram testados.
• Vários módulos de pagamento foram testados em conjunto.
• Carrinhos de compras realistas com descontos e frete foram testados.

Conclusão

Um gateway de pagamento personalizado no PrestaShop é mais do que uma simples integração de API.

A API é apenas uma parte da implementação. O verdadeiro desafio de engenharia começa quando o módulo de pagamento precisa coexistir com o checkout do PrestaShop, um OPC como o SuperCheckout, outros módulos de pagamento, JavaScript dinâmico, recálculos de carrinho e callbacks assíncronos do gateway.

Nossa experiência com problemas de compatibilidade de pagamentos reforçou uma abordagem importante: sempre isolar onde ocorre a falha antes de alterar o código.

Se o método de pagamento não for retornado pelo PHP, investigue o módulo de pagamento e suas regras de elegibilidade. Se o PHP o retornar, mas o cliente não o visualizar, investigue o OPC e a renderização do frontend. Se a interface do usuário aparecer, mas não responder, investigue o JavaScript e as atualizações AJAX. Se o pagamento for bem-sucedido, mas o pedido permanecer pendente, investigue o retorno de chamada e o fluxo de estado do pedido.

Essa abordagem é muito mais confiável do que presumir que todo problema de pagamento seja um problema de API.

Para desenvolvedores que trabalham em integrações de pagamento para PrestaShop, o objetivo não deve ser simplesmente fazer com que um gateway aceite uma transação. O objetivo é tornar todo o ciclo de vida do pagamento confiável — desde a primeira renderização da página de finalização da compra até o estado final de pedido verificado — mesmo quando vários métodos de pagamento e um OPC personalizado estão envolvidos.