Express Checkout: Apple Pay, Google Pay e Amazon Pay através da Stripe, guia completo
Instalar, ligar à Stripe (manual ou automático) e configurar o pagamento expresso Apple Pay, Google Pay e Amazon Pay na ficha de produto, no carrinho e no checkout para PrestaShop 8 e 9.
Apresentação
O DataFirefly Express Checkout acrescenta o pagamento por carteira digital, Apple Pay, Google Pay e Amazon Pay, à sua loja PrestaShop 8 ou 9, através da Stripe. O módulo apoia-se no Express Checkout Element da Stripe: um componente único que deteta automaticamente as carteiras disponíveis no dispositivo do cliente e mostra os botões correspondentes.
Os botões podem aparecer em três locais, ativáveis de forma independente: na ficha de produto (compra expresso), no carrinho e na página de pagamento. Depois do pagamento, a encomenda é criada e validada por um webhook Stripe com assinatura verificada, com uma lógica idempotente que impede qualquer encomenda em duplicado. O módulo é compatível com monoloja e multiloja, e é fornecido em cinco idiomas (FR, EN, ES, DE, IT).
Em Portugal, o Apple Pay e o Google Pay estão disponíveis através da Stripe para os cartões dos principais bancos; o MB WAY não faz parte do Express Checkout Element e passa por outros métodos de pagamento Stripe ou por um PSP local. O título mostrado acima dos botões e as cadeias do front-office traduzem-se para português em Internacional > Traduções.
Pré-requisitos
- PrestaShop 8.0 a 9.x, PHP 7.4 ou superior.
- A extensão PHP cURL ativada (verificada na instalação).
- Uma conta Stripe ativa.
- Uma loja servida em HTTPS (obrigatório para o Apple Pay e o Google Pay).
Instalação
- A partir do back-office, abra Módulos > Gestor de módulos.
- Clique em Instalar um módulo e carregue o arquivo ZIP do módulo.
- Terminada a instalação, clique em Configurar.
Na instalação, o módulo cria uma tabela de acompanhamento das transações e um estado de encomenda dedicado « Pagamento autorizado (à espera de captura) » usado pelo modo de captura manual.
Ligação à Stripe
O módulo propõe dois modos de ligação, definidos pelo campo Modo de ligação.
Modo manual (chaves API)
Preencha as suas chaves a partir do Dashboard Stripe (Programadores > Chaves API):
- Chave pública e Chave secreta, em versão Test e depois Live.
- Segredo do webhook (ver a secção Webhook abaixo).
Coloque o campo Modo em Test durante a integração e depois em Live em produção. Cada modo tem o seu próprio conjunto de chaves.
Modo automático (Stripe Connect / OAuth)
Este modo liga a sua conta Stripe num clique. Clique em Ligar com a Stripe, autorize o acesso, e o módulo recupera automaticamente as chaves pública e secreta, cria o webhook (e o seu segredo de assinatura) e tenta registar o domínio wallet para o Apple Pay / Google Pay. O botão Desligar revoga o acesso e purga as chaves.
O modo automático requer uma aplicação Stripe Connect. Duas possibilidades:
- A sua própria aplicação Connect: preencha o
client_ide o segredo de plataforma (Test e Live). - Broker DataFirefly: preencha o URL do broker, que detém o segredo de plataforma e realiza a troca OAuth. Se este URL estiver preenchido, tem prioridade.
Declare o URL de redirecionamento apresentado no painel de ligação ao nível dos Redirect URIs da sua aplicação Stripe Connect, caso contrário a autorização OAuth será recusada.
Configuração Stripe (Dashboard)
Webhook
Em modo manual, crie o endpoint em Programadores > Webhooks > Adicionar um endpoint:
- URL: o apresentado no topo da página de configuração do módulo (
.../module/dfexpresscheckout/webhook). - Eventos:
payment_intent.succeededepayment_intent.payment_failed. - Copie o segredo de assinatura (
whsec_…) para a configuração do módulo.
Em modo automático, o webhook e o seu segredo são criados automaticamente na ligação.
Sem segredo de webhook configurado, o módulo recusa as chamadas recebidas: é uma medida de segurança, a encomenda nunca é criada com base numa chamada não verificada.
Ativar as carteiras
- Amazon Pay: ative-o em Definições > Métodos de pagamento do seu Dashboard Stripe. Aparece depois automaticamente no Express Checkout Element.
- Apple Pay: o seu domínio deve estar verificado na Stripe (Definições > Apple Pay). Em modo automático, o módulo tenta esse registo por si.
- Google Pay: ativo automaticamente, nenhuma ação necessária.
Configuração do módulo
Locais de apresentação
Três interruptores controlam a apresentação dos botões: ficha de produto, carrinho e checkout. Ative-os de forma independente consoante a sua estratégia.
Modo de captura
- Captura imediata (por defeito): o pagamento é cobrado de imediato e a encomenda passa a « Pagamento aceite ».
- Autorização e captura manual: a Stripe autoriza o pagamento sem o cobrar; a encomenda chega ao estado « Pagamento autorizado (à espera de captura) ».
Título e tema
Personalize o título apresentado acima dos botões e o tema dos botões (preto, branco, branco com contorno) para o harmonizar com o seu design.
Do lado do cliente
Consoante o local, o cliente vê um ou vários botões wallet. Confirma o pagamento numa autenticação (Face ID, impressão digital, palavra-passe Amazon), sem criar conta: o e-mail e as moradas de entrega e de faturação são recuperados a partir da carteira. Quando se aplicam portes, o módulo propõe as transportadoras ativas e recalcula o total a cada mudança de morada. Os produtos desmaterializados funcionam sem etapa de entrega.
A partir da ficha de produto, a compra expresso incide sobre o produto apresentado (e a quantidade escolhida) através de um carrinho dedicado, sem modificar o carrinho atual do cliente.
Captura manual: cobrar ou cancelar
Em modo de captura manual, o controlo é feito pelo estado da encomenda:
- Para capturar o pagamento, passe a encomenda ao estado « Pagamento aceite ».
- Para libertar a autorização, passe a encomenda ao estado « Cancelada ».
Uma autorização Stripe tem uma duração de vida limitada (geralmente 7 dias). Lembre-se de capturar antes da expiração, caso contrário a autorização é libertada automaticamente.
Encomendas, webhook e idempotência
A encomenda é criada e validada na receção do evento payment_intent.succeeded (webhook assinado). Um controlador de retorno serve de rede de segurança quando o cliente volta à loja. Uma tabela de transações liga cada PaymentIntent à sua encomenda: uma mesma transação nunca gera portanto duas encomendas, qualquer que seja a ordem de chegada do retorno do navegador e do webhook. O cliente convidado e as suas moradas são reconstituídos a partir das informações devolvidas pela carteira.
Multilingue e multiloja
O módulo é fornecido com ficheiros de tradução FR, EN, ES, DE, IT e funciona em contexto multiloja. As chaves Stripe, o modo de ligação e o modo de captura são definições de configuração padrão.
Resolução de problemas
Os botões não aparecem
Verifique que a loja está em HTTPS, que as chaves Stripe estão preenchidas para o modo ativo (Test/Live) e que o local em causa está ativado. O Apple Pay só aparece no Safari/iOS com um domínio verificado; o Google Pay no Chrome/Android.
O pagamento é bem-sucedido mas não é criada nenhuma encomenda
Controle o webhook: URL correto, eventos payment_intent.succeeded e payment_intent.payment_failed, e segredo de assinatura idêntico ao do módulo. Consulte os registos Stripe (tentativas de entrega do webhook) e os registos do PrestaShop.
O Amazon Pay está ausente
Deve ser ativado em Definições > Métodos de pagamento do Dashboard Stripe. Aparece depois automaticamente.
A ligação automática falha
Verifique que o client_id Connect está preenchido para o modo ativo e que o URL de redirecionamento do módulo está declarado na sua aplicação Connect. Um token de estado inválido indica uma sessão expirada: relance a ligação a partir do back-office.
Desinstalação
A desinstalação retira a configuração do módulo. A tabela de acompanhamento das transações é conservada por defeito para a rastreabilidade das encomendas passadas.
FAQ
O Amazon Pay funciona mesmo através da Stripe?
Sim. A Stripe suporta o Amazon Pay no Express Checkout Element; basta ativá-lo no Dashboard Stripe.
É preciso instalar dependências (Composer)?
Não. O módulo incorpora um cliente Stripe interno em cURL. Basta instalar o módulo e preencher (ou ligar) as suas chaves.
O módulo é compatível com o PrestaShop 9?
Sim, é compatível com PrestaShop 8.0 a 9.x e testado em PHP 8.1 a 8.3.
Posso passar do modo manual ao modo automático?
Sim, a qualquer momento a partir da configuração. Em modo automático, as chaves são preenchidas pela ligação OAuth; em modo manual, introduz-las você mesmo.