VibeFox Square for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não ativa sem ele.

PHP: 8.0 ou superior.

Moeda da loja: 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. Não é necessário webhook: o plugin obtém 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 WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_square_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Square > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Mantenha o Sandbox Mode ativado e insira o Application ID, o Access Token e o Location ID do sandbox (veja Configuração). Salve: o plugin verifica as credenciais com a Square.

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

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Square. Acima dos campos, a página mostra Square Gateway is currently in SANDBOX mode. No real charges will be made. enquanto o modo sandbox estiver ativado. Ela avisa quando a Square está habilitada, mas o Application ID, o Access Token ou o Location ID do modo selecionado está ausente (o método de pagamento fica então oculto na finalização de compra), e quando a Square não consegue processar a moeda da loja. Na lista de métodos de pagamento, a Square mostra o selo Test mode enquanto o modo sandbox estiver ativado.

Ao salvar, o plugin verifica as credenciais do modo selecionado com a Square. Você verá um erro se a Square rejeitar o Access Token, se o Location ID não for encontrado para esse token, se as credenciais não puderem ser verificadas ou se a moeda do local for diferente da moeda da loja. A Square só pode cobrar na moeda do local: o plugin memoriza a moeda do local verificado e oculta o método de pagamento na finalização de compra para qualquer outra moeda, e a página de configurações continua exibindo o aviso. Ele também avisa se um Application ID de sandbox for usado no modo live, ou o contrário.

General

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

Title: o título do método de pagamento que o cliente vê durante a finalização de compra. Padrão: Credit / debit card.

Description: a descrição do método de pagamento que o cliente vê durante a finalização de compra. Padrão: Pay securely with your credit or debit card via Square.

Square account

Abra o Square Developer Dashboard, 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 corresponder à 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, e os campos de live quando estiver desativado.

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

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

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

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

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

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

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

Advanced

Debug log: Log API requests and responses. Os erros são sempre registrados. Ative para registrar também cada requisição, sem dados de cartão ou chaves. Os logs ficam em WooCommerce > Status > Logs, origem wcp_square_gateway. Padrão: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. Exclui as configurações do gateway e os arquivos de log ao excluir o plugin. Os dados de pagamento dos pedidos são mantidos. Padrão: off.

Finalização de compra

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. No modo sandbox, a finalização de compra mostra um aviso de sandbox. Quando o cliente clica em Place order, o cartão é tokenizado no navegador com verificação do comprador (3-D Secure / SCA): valor, moeda e contato de cobrança são enviados à Square, e o banco do cliente pode pedir uma confirmação. Seu servidor recebe apenas um token de uso único.

Em seguida, o plugin cobra o token pela API de pagamentos da Square pelo total do pedido na moeda do pedido, com o ID do pedido como referência, uma nota Order # com o número do pedido e o nome do seu site, e o e-mail de cobrança. 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 pedido, moeda, ID do pedido e local. Depois, o cliente vai para a página de pedido recebido. Se o pagamento não for COMPLETED ou algum valor for diferente, o pedido é colocado em espera com uma nota, e o cliente ainda assim vai para a página de pedido recebido.

Só uma tentativa de pagamento por pedido é executada por vez. Se o cliente clicar duas vezes ou pagar em duas abas, a segunda tentativa mostra 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 pedido, token e valor nunca criam um segundo pagamento.

Se a Square não responder (problema de rede, tempo esgotado, erro do servidor), a requisição é repetida uma vez com a mesma chave de idempotência. Se ainda não houver resposta, o cliente vê Não foi possível obter uma confirmação do provedor de pagamento. Aguarde um minuto e tente novamente. Se seu cartão já foi cobrado, o pagamento será reconhecido e você não será cobrado duas vezes. A nota do pedido pede que você verifique o Square Dashboard. Na próxima tentativa, o plugin primeiro procura na Square o pagamento anterior deste pedido e conclui o pedido com ele, em vez de cobrar o cartão novamente.

Quando o banco recusa o cartão, o cliente vê 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 e tente novamente. ou Seu banco exige verificação adicional (3-D Secure). Digite o cartão novamente e conclua a verificação. O motivo técnico vai para as notas do pedido e para o log. O cliente pode tentar novamente com outro cartão, inclusive depois, pela página Pay for order.

O método de pagamento funciona na finalização de compra clássica, no bloco Checkout e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita apenas pagamentos com cartão, capturados imediatamente. Não há cartões salvos nem perfis de cliente, WooCommerce Subscriptions ou Pre-Orders, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH ou cartões-presente Square, pagamentos somente com autorização, webhooks da Square, nem sincronização de produtos ou estoque com a Square. As contestações são gerenciadas no Square Dashboard.

Pedidos e reembolsos

Status do pedido

Pending payment: o pedido foi criado e ainda não foi pago, por exemplo após um cartão recusado ou uma resposta perdida da Square.

Processing: a Square confirmou um pagamento COMPLETED do total do pedido. Este é o status padrão do WooCommerce após o pagamento (pedidos com apenas produtos virtuais para download passam a Concluído). A nota do pedido mostra o ID do pagamento na Square, a bandeira do cartão com os últimos 4 dígitos e o modo (sandbox ou live). O ID da transação é o ID do pagamento na Square e, na tela do pedido, leva ao pagamento no Square Dashboard.

On hold: a Square respondeu com um pagamento que não é COMPLETED, ou com valor, moeda, referência ou local diferentes. A nota Square payment needs review mostra o ID do pagamento, o status e os valores. Verifique a captura, o valor e a moeda no Square Dashboard antes de enviar o pedido.

O plugin armazena no pedido o ID do pagamento na Square, a bandeira do cartão e os últimos 4 dígitos, o ambiente e o local. Números de cartão nunca são armazenados.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit / debit card (o botão mostra o seu Title). Reembolsos totais e parciais são suportados. O reembolso é enviado ao ambiente (sandbox ou produção) e ao local em que o pagamento foi feito, por isso 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) é adicionado às notas do pedido com o ID do reembolso na Square. Se a Square o recusar, o WooCommerce mostra o erro e nenhum reembolso é registrado.

A Square conclui os reembolsos do lado dela. Um reembolso que a Square recusar depois não é informado ao WooCommerce, e os reembolsos feitos no Square Dashboard não aparecem no WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Square. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site 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ê Este método de pagamento não está disponível. Escolha outro. Os gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pedidos pagos continuam pagos, e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

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á ligado e se o Application ID, o Access Token e o Location ID do modo atual estão preenchidos. Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é USD, CAD, AUD, JPY, GBP ou EUR e é igual à moeda do seu local na Square. A página de configurações mostra um aviso para cada um desses problemas.

O formulário de cartão não carrega: o cliente vê O formulário de 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 de cartão ainda está carregando. Aguarde um momento e tente novamente.

Os pagamentos são recusados, embora o cartão esteja correto: a moeda do local deve ser igual à moeda da loja. Salve as configurações para ver o resultado da verificação de credenciais; após uma verificação bem-sucedida, o método fica oculto para outras moedas.

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 uma confirmação do provedor de pagamento»: a Square não respondeu. Leia a nota do pedido e verifique os pagamentos deste local no Square Dashboard (referência = ID do pedido). Se o cliente tentar novamente, o plugin primeiro procura o pagamento anterior e conclui o pedido com ele, em vez de cobrar de novo.

O pedido está On hold: leia a nota Square payment needs review. O pagamento não era COMPLETED, ou seu valor, moeda ou local eram diferentes do pedido. Verifique no Square Dashboard e depois envie 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. Insira-o e tente novamente.

Outros erros: ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_square_gateway.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway e os arquivos de log são removidos apenas se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, os IDs de pagamento da Square e os IDs de transação.

Square é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado à Square nem endossado por ela.