VibeFox Square for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Moeda: a moeda do carrinho deve ser a moeda do seu local na Square: USD, CAD, AUD, JPY, GBP ou EUR. Para outras moedas, o método de pagamento fica oculto na finalização de compra. A Square atende vendedores nos Estados Unidos, Canadá, Austrália, Japão, Reino Unido, Irlanda, França e Espanha.

Conta Square: você precisa de um aplicativo no Square Developer Dashboard. Nele você copia o Application ID e o Access Token (página Credentials) e o Location ID (página Locations). Sandbox e Production têm valores separados. Nenhum webhook é necessário: o módulo recebe o resultado do pagamento diretamente da resposta da Square.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.

2. Quando o envio terminar, clique em Configure ou encontre depois o VibeFox Square Gateway na lista de módulos e clique em Configure.

3. Digite sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).

4. Mantenha o Sandbox Mode ativado e digite o Application ID, o Access Token e o Location ID do sandbox (veja Configuração). Clique em Save: o módulo verifica as credenciais com a Square.

5. Ative o Enable/Disable, salve e teste um pagamento com os cartões de teste do guia de testes do sandbox da Square. Depois desative o Sandbox Mode, digite as credenciais de produção e salve de novo.

Na instalação, o módulo cria o status de pedido Square payment on hold. O PrestaShop permite que um novo módulo de pagamento seja usado nas moedas, nos países ativos no momento da instalação e nos grupos de clientes. Verifique-os e marque os países adicionados depois em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Square Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Square Gateway está atualmente no modo SANDBOX. Nenhuma cobrança real será feita. enquanto o modo sandbox estiver ativado. Ela avisa quando a Square está ativada, mas faltam o Application ID, o Access Token ou o Location ID do modo selecionado (o método de pagamento fica então oculto na finalização de compra), quando a Square não consegue processar a moeda padrão da sua loja e quando a moeda do seu local na Square é diferente dela.

Ao salvar, o módulo verifica com a Square as credenciais do modo selecionado. As configurações são salvas em qualquer caso. Você vê um aviso se a Square rejeitar o Access Token, se o Location ID não for encontrado para esse token, se as credenciais não puderam ser verificadas ou se a moeda do local for diferente da moeda da loja. A Square só pode cobrar na moeda do local: o módulo guarda a moeda do local verificado e oculta o método de pagamento para carrinhos em qualquer outra moeda. Também avisa se um Application ID de sandbox for usado no modo live, ou o contrário.

Square

Enable/Disable: Enable Square Payment Gateway ativa ou desativa o método de pagamento. Padrão: off.

Title: o título do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Credit / debit card. Obrigatório.

Description: a descrição do método de pagamento que o cliente vê na finalização de compra. Padrão: Pay securely with your credit or debit card via Square. No modo sandbox, (SANDBOX MODE) é acrescentado.

Conta Square

Abra o Square Developer Dashboard (a seção tem um link), escolha seu aplicativo e copie o Application ID e o Access token da página Credentials (Sandbox e Production têm valores separados) e o Location ID da página Locations. A moeda do local deve ser igual à moeda da sua loja. A página mostra apenas os campos de credenciais do modo selecionado: os campos de sandbox enquanto o Sandbox Mode estiver ativado, os campos live quando estiver desativado. Os dois conjuntos continuam salvos.

Sandbox Mode: os pagamentos vão para o sandbox da Square e nenhum dinheiro real é cobrado. Use cartões de teste da Square. Padrão: on.

Sandbox Application ID: seu Application ID da Square para sandbox (começa com sandbox-sq0idb-).

Sandbox Access Token: seu Access Token da Square para sandbox.

Sandbox Location ID: seu Location ID da Square para sandbox.

Live Application ID: seu Application ID da Square de produção (começa com sq0idp-).

Live Access Token: seu Access Token da Square de produção.

Live Location ID: seu Location ID da Square de produção.

Access tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo — deixe vazio para mantê-lo. Digite um novo valor apenas se quiser alterá-lo.

Clear saved secrets: marque um access token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Avançado

Debug log: erros e avisos são sempre registrados. Ative para registrar também cada requisição e resposta, sem dados de cartão nem chaves, em logs/wc_sqg_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Padrão: off.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ativado, ao desinstalar o módulo são removidas as configurações do gateway e os arquivos de log. Os pagamentos e reembolsos Square dos pedidos e o status de pedido Square payment on hold são sempre mantidos. Padrão: off.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Credit / debit card) e digita o cartão no formulário da Square exibido abaixo da descrição. Quando o cliente confirma o pedido, o cartão é tokenizado no navegador com verificação do comprador (3-D Secure / SCA): o total do carrinho, a moeda e o endereço de cobrança são enviados à Square, e o banco do cliente pode pedir uma confirmação. Sua loja recebe apenas um token de uso único.

Em seguida, o módulo cobra o token pela API de pagamentos da Square pelo total do carrinho na moeda do carrinho, com o ID do carrinho como referência, uma nota Cart # com o número do carrinho e o nome da sua loja, e o e-mail do cliente. O pagamento é capturado imediatamente. O pedido só é marcado como pago depois que a Square confirma: a resposta da Square deve mostrar um pagamento COMPLETED com valor exatamente igual ao total do carrinho, moeda, ID do carrinho e local. Então o pedido é criado com Payment accepted, e o cliente vê a página padrão de confirmação do pedido com Seu pagamento com cartão foi recebido. e um link para o recibo da Square. Se o pagamento não for COMPLETED ou algum valor não corresponder, o pedido é criado em Square payment on hold e a página mostra Seu pagamento com cartão foi recebido e está em análise. Atualizaremos seu pedido assim que a análise for concluída.

Apenas uma tentativa de pagamento por carrinho é executada por vez. Se o cliente clicar duas vezes ou pagar em duas abas, a segunda tentativa vê Este pedido já está sendo pago. Aguarde um momento e verifique seu e-mail antes de tentar novamente. As requisições são idempotentes: o mesmo carrinho, o mesmo token de cartão e o mesmo valor nunca criam um segundo pagamento, e um carrinho que já tem pedido nunca é cobrado novamente.

Se a Square não responder (problema de rede, tempo esgotado, erro no servidor), a requisição é repetida uma vez com a mesma chave de idempotência. Se ainda não houver resposta, o módulo procura imediatamente o pagamento deste carrinho na Square. Se encontrá-lo, o pedido é criado com ele. Se nenhum pagamento for encontrado, o cliente permanece na finalização de compra com Não foi possível obter a confirmação do provedor de pagamento. Aguarde um minuto e tente novamente — se o seu cartão já tiver sido cobrado, o pagamento será reconhecido e você não será cobrado duas vezes. A próxima tentativa procura primeiro o pagamento anterior. Se a Square também não puder ser acessada para essa consulta, o pedido é criado em Square payment on hold sem pagamento, com uma nota de que o cartão pode ter sido cobrado, e a página de confirmação mostra Não foi possível obter a confirmação do seu pagamento com cartão da Square. Verifique seu e-mail e o extrato do cartão antes de pagar novamente, ou entre em contato conosco.

Quando o banco recusa o cartão, nenhum pedido é criado e o cliente permanece na finalização de compra com uma mensagem curta de acordo com o código de erro da Square, por exemplo Seu cartão foi recusado. Use outro cartão ou método de pagamento., O código de segurança do cartão (CVV) está incorreto. Verifique-o e tente novamente. ou Seu banco exige verificação adicional (3-D Secure). Digite o cartão novamente e conclua a verificação. O carrinho é mantido, e o cliente pode tentar novamente com outro cartão. O motivo técnico vai para o log.

O módulo aceita apenas pagamentos com cartão, capturados imediatamente. Não há cartões salvos nem perfis de cliente, assinaturas, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ou cartões-presente Square, não há pagamentos somente com autorização, webhooks da Square nem sincronização de produtos ou estoque com a Square. As disputas são gerenciadas no Square Dashboard.

Pedidos e reembolsos

Status do pedido

No order yet: o cartão foi recusado, ou a resposta da Square se perdeu e nenhum pagamento foi encontrado. Existe apenas o carrinho.

Payment accepted: a Square confirmou um pagamento COMPLETED do total do carrinho. O pagamento é registrado com o ID de pagamento da Square como ID de transação, e uma nota mostra o ID do pagamento, a bandeira do cartão com os últimos 4 dígitos e o modo (sandbox ou live).

Square payment on hold: a Square respondeu com um pagamento que não está COMPLETED (por exemplo APPROVED), ou com valor, moeda, referência ou local diferentes. A nota O pagamento Square precisa de análise mostra o ID do pagamento, o status e os valores. Um pagamento COMPLETED é registrado no pedido com o valor que a Square cobrou. Este status também é usado quando o carrinho foi alterado durante o pagamento, e quando a resposta da Square se perdeu e não pôde ser verificada (nesse caso nenhum pagamento é registrado). Verifique o pagamento no Square Dashboard antes de preparar o envio.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Se um segundo pagamento chegar para um carrinho que já tem pedido, o pedido não é alterado. Uma nota pede que você verifique e reembolse a duplicata no Square Dashboard.

Bloco Square

A página do pedido mostra um bloco Square com o ID do pagamento na Square (com link para o pagamento no Square Dashboard), o status na Square, a bandeira do cartão e os últimos 4 dígitos, os valores Paid / order / refunded, o ambiente e o local, um link para o recibo da Square, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as Square notes do pedido. Números de cartão nunca são armazenados.

Reembolsos

No bloco Square, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Square. Confirme a pergunta Reembolsar este valor pela Square? Esta ação não pode ser desfeita. Há suporte a reembolsos totais e parciais. Você precisa ter permissão para editar pedidos. Os reembolsos são feitos no valor e na moeda que a Square cobrou; por isso, após uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado ao ambiente (sandbox ou produção) e ao local em que o pagamento foi feito, então o Access Token desse modo precisa estar configurado. As requisições de reembolso são idempotentes e são repetidas uma vez se a Square não responder. Um reembolso aceito pela Square (status PENDING ou COMPLETED) é incluído no histórico de reembolsos e nas notas, com o ID do reembolso na Square. Se a Square o rejeitar, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.

O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Square. A Square conclui os reembolsos do lado dela: um reembolso que a Square rejeite depois não é informado de volta, e reembolsos feitos no Square Dashboard não aparecem no PrestaShop.

Chave de licença

O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Square Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Square Gateway > Configure, acima das configurações. Cole a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-square e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois de alterar o endereço da loja, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Square não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A loja do PrestaShop não sabe que você está logado no back office, então o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados: pedidos pagos continuam pagos, e os reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A Square não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ativado e se o Application ID, o Access Token e o Location ID do modo atual estão preenchidos. Verifique se a moeda do carrinho é USD, CAD, AUD, JPY, GBP ou EUR e se é igual à moeda do seu local na Square. A página de configurações mostra um aviso para cada um desses problemas. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.

O formulário do cartão não carrega: o cliente vê O formulário do cartão não pôde ser carregado. Recarregue a página ou escolha outro método de pagamento. Verifique se o Application ID e o Location ID pertencem ao modo selecionado (IDs de sandbox começam com sandbox-). Se o cliente clicar cedo demais, aparece O formulário do cartão ainda está carregando. Aguarde um momento e tente novamente.

O método de pagamento sumiu depois de salvar: a moeda do local na Square é diferente da moeda do carrinho. Digite o Location ID de um local da Square na moeda da sua loja e salve novamente: o método volta a aparecer após uma verificação bem-sucedida.

A Square rejeitou o Access Token do modo selecionado: o token pertence ao outro modo ou está errado. Copie-o novamente da página Credentials do seu aplicativo e verifique o Sandbox Mode.

O Location ID não foi encontrado para este Access Token: copie o Location ID da página Locations do mesmo aplicativo e do mesmo modo.

O cliente viu Não foi possível obter a confirmação do provedor de pagamento: a Square não respondeu e nenhum pagamento foi encontrado ainda. Verifique os pagamentos deste local no Square Dashboard (referência = ID do carrinho). Se o cliente tentar novamente, o módulo procura primeiro o pagamento anterior e cria o pedido com ele, em vez de cobrar de novo.

O cliente viu Seu pagamento foi recebido, mas o pedido não pôde ser concluído automaticamente: o cartão foi cobrado, mas o PrestaShop não conseguiu criar o pedido (por exemplo, porque o módulo estava desativado naquele momento). Leia o log e depois crie o pedido manualmente ou reembolse o pagamento no Square Dashboard.

O pedido está em Square payment on hold: leia as notas do bloco Square (veja Status do pedido). Verifique o pagamento no Square Dashboard e depois prepare o pedido ou reembolse o pagamento.

O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo sandbox ou live, e o Access Token desse modo não está configurado. Digite-o e tente novamente.

Outros erros: ative o Debug log e veja o campo Log na página do módulo.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Square Gateway e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Se o Delete data on uninstall estiver ativado, as configurações do gateway e os arquivos de log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação futura. Os pagamentos e reembolsos Square dos pedidos e o status de pedido Square payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento, IDs de pagamento Square e IDs de transação.

Square é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Square.