VibeFox Square for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 ou superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: a moeda do pedido deve ser a moeda da sua localização no Square: USD, CAD, AUD, JPY, GBP ou EUR. Para outras moedas, o método de pagamento fica oculto na finalização de compra. JPY é cobrado em ienes inteiros.

Conta no Square: você precisa de um aplicativo no Square Developer Dashboard. Dele você copia o Application ID e o Access Token (página Credentials) e o Location ID (página Locations). Os valores de Sandbox e Production são separados. Não é necessário nenhum webhook: a extensão recebe o resultado do pagamento diretamente da resposta do Square.

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

Instalação

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3, wcp_square_gateway-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_square_gateway.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_square_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Square Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão de lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja Chave de licença).

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

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

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_square_gateway.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Square Gateway, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as credenciais do Square como nas etapas 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Uma instalação nova começa com o método de pagamento desativado e o sandbox ativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Square Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página mostra Square Gateway está atualmente em modo SANDBOX. Nenhuma cobrança real será feita. enquanto o sandbox estiver ativado. Ela avisa quando o Square está ativado, 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 o Square não consegue processar a moeda padrão da sua loja e quando a moeda da sua localização no Square é diferente dela. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode estar vazio (até 128 caracteres), Sort Order deve ser um número inteiro (valores negativos são permitidos), Total deve ser um número igual ou maior que 0, e a zona geográfica e os status de pedido indicados precisam existir; caso contrário, nada é salvo. Em seguida, a extensão verifica as credenciais do modo selecionado no Square. As configurações são salvas em qualquer caso, e os avisos aparecem em um bloco vermelho acima das configurações: o Square rejeitou o Access Token, o Location ID não foi encontrado para esse token, não foi possível verificar as credenciais ou a moeda da localização é diferente da moeda da loja. O Square só pode cobrar na moeda da localização: a extensão guarda a moeda da localização verificada e oculta o método de pagamento para pedidos em qualquer outra moeda. Ela também avisa se um Application ID de sandbox for usado em modo de produção, ou o contrário.

Square

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

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

Description: o texto exibido ao cliente na etapa Confirm Order, acima do formulário do cartão. Padrão: Pay securely with your credit or debit card via Square.

Sort Order: a posição do pagamento com cartão entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro (valores negativos são permitidos).

Geo Zone: oferecer o formulário do cartão apenas para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que o método de pagamento seja oferecido. Deixe em branco para oferecê-lo em qualquer total.

Conta no Square

Abra o Square Developer Dashboard (a seção tem um link para ele), 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 da localização deve ser a mesma moeda da sua loja. A página mostra apenas os campos de credenciais do modo selecionado: os campos do sandbox enquanto Sandbox Mode estiver ativado, e os campos de produção quando estiver desativado. Os dois conjuntos continuam salvos.

Sandbox Mode: os pagamentos vão para o sandbox do Square e nenhum dinheiro real é cobrado. Use os cartões de teste do Square. Padrão: ativado. Os reembolsos de um pedido sempre usam o ambiente e a localização em que o pedido foi pago.

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

Sandbox Access Token: seu Access Token do Square no sandbox.

Sandbox Location ID: seu Location ID do Square no sandbox.

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

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

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

Os Access Tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo — deixe em branco para manter. Digite um valor novo somente se quiser alterá-lo. Para remover um Access Token salvo, marque Clear the saved value on save abaixo do campo e clique em Save.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido incompleto). O pedido só recebe um status depois que o Square responde ao pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o Square concluiu o pagamento exatamente pelo valor e pela moeda do pedido. Padrão: Processing.

On Hold (Review) Status: o pagamento precisa da sua revisão (veja Status de pedido). Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Refunded Status: definido depois que o pagamento é totalmente reembolsado pela aba do pedido. Padrão: Refunded.

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 wc_sqg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para wc_sqg_debug.old.log.php. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações do gateway e os arquivos de log. Os pagamentos e reembolsos do Square dos pedidos são sempre mantidos. Padrão: desativado.

Importar / Exportar

Exportar: Download JSON salva as configurações em um arquivo JSON. Os Access Tokens não são exportados.

Importar: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. Os Access Tokens salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão Credit / debit card). Na etapa Confirm Order, o cliente vê Credit / debit card (Square), a sua descrição, MODO SANDBOX — nenhuma cobrança real será feita. enquanto o sandbox estiver ativado, e o formulário de cartão do Square. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, o cartão é tokenizado no navegador com verificação do comprador (3-D Secure / SCA): o total do pedido, a moeda e o endereço de pagamento são enviados ao Square, e o banco do cliente pode pedir uma confirmação. Sua loja recebe apenas um token de uso único. No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco de método de pagamento, na janela Payment method options. O formulário do cartão Square então aparece no bloco de confirmação, no final da página de finalização de compra, acima de Confirm Order.

Em seguida, a extensão cobra o token pela API de pagamentos do Square pelo total do pedido na moeda do pedido, com o número do pedido como referência, uma nota Order # com o número do pedido e o nome da sua loja, e o e-mail do cliente. O pagamento é capturado imediatamente. O pedido só é marcado como pago depois que o Square confirma: a resposta do Square precisa mostrar um pagamento COMPLETED exatamente com o total do pedido, a moeda, o número do pedido e a localização. O pedido então recebe Order Status After Payment da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart com Recebemos o seu pagamento com cartão. e um link View the receipt para o recibo do Square. Se o pagamento não for COMPLETED ou algum valor divergir, o pedido recebe On Hold (Review) Status e a página mostra Recebemos o seu pagamento com cartão e ele está em análise. Atualizaremos o 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, e o OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, então a extensão acompanha o carrinho: um carrinho já pago nunca é cobrado novamente, e o cliente vai direto para a página de sucesso.

Se o 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, a extensão procura imediatamente o pagamento deste pedido no Square. Se encontrá-lo, o pedido recebe o status a partir dele. Se nenhum pagamento for encontrado, o cliente permanece na etapa Confirm Order com Não foi possível obter uma 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 do mesmo carrinho procura primeiro o pagamento anterior novamente. Se o Square também não puder ser acessado para essa consulta, o pedido recebe On Hold (Review) Status sem pagamento, com uma nota de que o cartão pode ter sido cobrado, e a página de sucesso mostra Não foi possível obter uma confirmação do seu pagamento com cartão pelo 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, o pedido permanece sem status e o cliente continua na etapa Confirm Order com uma mensagem curta de acordo com o código de erro do 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 os dados do 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 é gravado no log.

OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza: se o cartão for recusado, o cliente paga o mesmo pedido novamente, e se o Square não responder ao pagamento, a próxima tentativa desse pedido procura primeiro o pagamento anterior. Se o pedido da finalização de compra já tiver um status (foi pago ou fechado pela loja) e o carrinho tiver produtos novos, o cliente volta à finalização de compra e o novo carrinho é pago com um novo pedido.

A extensão aceita somente pagamentos com cartão, capturados imediatamente. Não há cartões salvos, perfis de cliente, assinaturas, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ou vales-presente do Square, nem pagamentos somente com autorização, nem webhooks do Square, nem sincronização de produtos ou estoque com o Square. As contestações são gerenciadas no Square Dashboard.

Pedidos e reembolsos

Status de pedido

Sem status (pedido incompleto): o cliente ainda não pagou, o cartão foi recusado, ou a resposta do Square se perdeu e nenhum pagamento foi encontrado. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): o Square confirmou um pagamento COMPLETED do total do pedido. Uma nota mostra o ID do pagamento no Square, a bandeira do cartão com os últimos 4 dígitos e o modo (sandbox ou produção).

On Hold (Review) Status (padrão Pending): o Square respondeu com um pagamento que não é COMPLETED (por exemplo APPROVED ou PENDING), ou com outro valor, moeda, referência ou localização. A nota O pagamento do Square precisa de revisão mostra o ID do pagamento, o status e os valores. Esse status também é usado quando o pedido foi alterado durante o pagamento, e quando a resposta do Square se perdeu e não pôde ser verificada (nesse caso nenhum pagamento é registrado, e a nota pede que você confira os pagamentos da localização no Square Dashboard usando o número do pedido como referência). Verifique o pagamento no Square Dashboard antes de atender o pedido.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

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

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Square Gateway

Em Sales > Orders, abra um pedido pago com o Square. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Square Gateway mostra o Payment ID do Square (com link para o pagamento no Square Dashboard) com um rótulo Sandbox para pagamentos de teste, o Status do Square, a bandeira do Card e os últimos 4 dígitos, os valores Paid / order / refunded, o Environment / location, o link para o Square receipt, o formulário de reembolso, o histórico de reembolsos e as Square notes do pedido. Números de cartão nunca são armazenados. A aba é exibida para usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Square Gateway, informe o Amount (o valor ainda não reembolsado é preenchido), opcionalmente um Reason (optional), e clique em Refund via Square. Confirme a pergunta Reembolsar este valor pelo Square? Esta ação não pode ser desfeita. Reembolsos totais e parciais são suportados. Você precisa da permissão para modificar a extensão (definida em System > Users > User Groups). Os reembolsos são feitos no valor e na moeda que o Square cobrou, então, 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 à localização em que o pagamento foi feito, então o Access Token desse modo precisa estar definido. As requisições de reembolso são idempotentes e são repetidas uma vez se o Square não responder. Um reembolso aceito pelo Square (status PENDING ou COMPLETED) é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso no Square. Se o Square o recusar, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso total define o pedido como Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não altera o status.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pelo Square. O Square conclui os reembolsos do lado dele: um reembolso que o Square recusar depois não é informado de volta, e reembolsos feitos no Square Dashboard não aparecem no OpenCart.

Chave de licença

A extensão 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 Extensions > Extensions > Payments > VibeFox Square Gateway > Edit, 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-square e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Chave não encontrada, Esta chave pertence a outro produto, Limite de domínios atingido ou Licença expirada em seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o Square não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Escolha outro. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4, essa prévia não está disponível: a loja não vê o login no painel administrativo, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Pedidos existentes não são afetados: pedidos pagos continuam pagos, e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O Square não aparece na finalização de compra: verifique se a licença está ativa, se 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 cliente é USD, CAD, AUD, JPY, GBP ou EUR e se é igual à moeda da sua localização no Square. A página de configurações mostra um aviso para cada um desses problemas. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O formulário do cartão não carrega: o cliente vê Não foi possível carregar o formulário do cartão. 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 desapareceu depois de salvar: a moeda da localização no Square é diferente da moeda do pedido. Informe o Location ID de uma localização do Square na moeda da sua loja e salve novamente: o método volta a aparecer depois de uma verificação bem-sucedida.

O Square rejeitou o Access Token do modo selecionado: o token pertence ao outro modo ou está incorreto. Copie-o novamente da página Credentials do seu aplicativo e confira 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 a mensagem «Não foi possível obter uma confirmação do provedor de pagamento»: o Square não respondeu e nenhum pagamento foi encontrado ainda. Verifique os pagamentos desta localização no Square Dashboard (referência = número do pedido). Se o cliente tentar de novo, a extensão procura primeiro o pagamento anterior e o usa, em vez de cobrar novamente.

O cliente viu a mensagem «Recebemos o seu pagamento, mas o pedido não pôde ser concluído automaticamente»: o cartão foi cobrado, mas o OpenCart não conseguiu definir o status do pedido. Leia o log e depois conclua o pedido manualmente ou reembolse o pagamento no Square Dashboard.

O cliente vê a mensagem «Este método de pagamento não está disponível para o seu pedido»: a finalização de compra não corresponde mais ao pedido, o método de pagamento foi desativado nesse meio tempo, ou a moeda do pedido não pode ser cobrada. O cliente recarrega a finalização de compra ou escolhe outro método de pagamento.

O pedido está no status de revisão após o pagamento: leia as notas na aba VibeFox Square Gateway (veja Status de pedido). Verifique o pagamento no Square Dashboard e depois atenda o pedido ou reembolse o pagamento.

Não há formulário de reembolso na aba: a aba informa o motivo: nenhum pagamento do Square cobrou dinheiro por este pedido, nenhum ID de pagamento do Square está registrado (a aba indica então a localização e o número do pedido a procurar no Square Dashboard), o pagamento foi totalmente reembolsado, ou o seu grupo de usuários não tem permissão para modificar a extensão.

O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo sandbox ou de produção, e o Access Token desse modo não está definido. Informe-o e tente novamente.

Outros erros: ative Debug log e consulte o campo Log na página da extensão.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Square Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma reinstalação. O evento do OpenCart da extensão também é removido. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, credenciais, registro de log) e os arquivos de log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os pagamentos e reembolsos do Square dos pedidos são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados depois de uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Square Gateway na lista de extensões instaladas. Depois, clique em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

Square é uma marca comercial de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo Square.