VibeFox Pin Payments for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

WooCommerce: 7.1 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

HTTPS: a sua finalização de compra deve usar HTTPS, como exigido para aceitar pagamentos com cartão (PCI DSS). Os dados do cartão são enviados do navegador do cliente diretamente para a Pin Payments pelo Pin.js e nunca chegam ao seu servidor, por isso a loja se enquadra no PCI SAQ A-EP.

Conta na Pin Payments: uma conta de comerciante na Pin Payments (para empresas da Austrália ou da Nova Zelândia; os clientes podem pagar de qualquer lugar). Você precisa da chave publicável e da chave secreta, para produção e, para testes, do ambiente de teste. Não é necessário um segredo de webhook: o plugin não usa webhooks.

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

Instalação

1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_pinpayments_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. No painel da Pin Payments, abra Account > API Keys e copie as suas chaves de teste para Test publishable key e Test secret key. Mantenha Test mode ativado, ative Enable/Disable e salve.

6. Faça um pedido de teste com um cartão de teste da Pin Payments. Quando tudo estiver funcionando, insira as chaves de produção, desative Test mode e salve.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Pin Payments. Acima dos campos, a página exibe um aviso enquanto o modo de teste estiver ativo, um erro enquanto a chave publicável ou a chave secreta do modo atual estiver vazia, e um erro quando a Pin Payments não oferece suporte à moeda da loja (com a lista de moedas aceitas). Nesses dois últimos casos, o gateway fica oculto na finalização de compra. Depois de salvar, os avisos já refletem o novo modo e as novas chaves. Na lista de métodos de pagamento, o gateway aparece como pendente de configuração até que o modo atual tenha as duas chaves.

Enable/Disable: Enable Pin Payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento exibido na finalização de compra. Padrão: Credit card (Pin Payments).

Description: a descrição do método de pagamento exibida na finalização de compra. Padrão: Pay with your credit card via Pin Payments.

Chaves de API

Você encontra as chaves no painel da Pin Payments, em Account > API Keys. As chaves de teste funcionam somente com a API de teste, e as de produção somente com a API de produção. A chave publicável é usada pelo Pin.js no navegador do cliente. A chave secreta nunca sai do seu servidor.

Test mode: Enable test mode. Usa o ambiente de teste da Pin Payments (test-api.pinpayments.com) e as chaves de teste. Nenhuma cobrança real é feita, e os clientes veem MODO DE TESTE — nenhuma cobrança real será feita. no formulário do cartão. Quando está desativado, são usados a API de produção (api.pinpayments.com) e as chaves de produção. Padrão: ativado.

Test publishable key: a chave publicável da sua conta de teste na Pin Payments.

Test secret key: a chave secreta da sua conta de teste na Pin Payments. É um campo de senha.

Live publishable key: a chave publicável da sua conta de produção na Pin Payments.

Live secret key: a chave secreta da sua conta de produção na Pin Payments. É um campo de senha.

Espaços em volta das chaves são removidos. As duas chaves do modo atual devem estar preenchidas, senão o gateway não é exibido na finalização de compra.

Avançado

Debug log: Log Pin Payments API calls — os registros são gravados em WooCommerce > Status > Logs, origem wcp_pinpayments_gateway. Os erros são sempre registrados; ative esta opção para registrar também cada chamada à API. Dados de cartão, chaves de API e dados pessoais dos clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados de pagamento armazenados nos pedidos são sempre mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Credit card (Pin Payments), com os ícones de Visa, Mastercard e American Express) e preenche Card number, Expiry (MM / YY), CVC e Name on card na sua finalização de compra. Antes do envio, o formulário do cartão verifica o tamanho do número do cartão, o mês e o ano de validade, um CVC de 3 ou 4 dígitos e o nome.

Ao fazer o pedido, o Pin.js envia do navegador os dados do cartão e o endereço de cobrança diretamente para a Pin Payments e obtém um token de cartão de uso único. Somente esse token é enviado ao seu servidor. Em seguida, o seu servidor cria uma cobrança capturada no valor total do pedido, na moeda do pedido, com a descrição <store name> - Order <number>. A Pin Payments responde na mesma requisição. O pedido só é marcado como pago quando a Pin Payments informa uma cobrança bem-sucedida, e somente para exatamente o valor e a moeda do pedido. Depois, o cliente é levado à página de pedido recebido.

Somente uma tentativa de pagamento por pedido é executada por vez. Um segundo envio recebe Este pedido já está sendo pago. Aguarde um momento e verifique o seu e-mail antes de tentar novamente. Um pedido já pago, ou cobrado e retido, nunca é cobrado novamente. Um token de cartão só pode ser usado uma vez: após uma tentativa com falha, ou quando o cliente altera os dados do cartão, um novo token é criado.

Mensagens que o cliente pode ver: Seu cartão foi recusado. Use outro cartão ou entre em contato com o seu banco.; Seu cartão não tem saldo suficiente. Use outro cartão.; Seu cartão está vencido. Use outro cartão.; O código de segurança do cartão (CVC) está incorreto.; Este tipo de cartão não é aceito. Use Visa, Mastercard ou American Express.; Falha no pagamento: com o motivo informado pela Pin Payments para os dados recusados; Os dados do seu cartão expiraram. Digite-os novamente e tente outra vez. quando o token não pode ser usado; Não foi possível carregar o formulário seguro do cartão. Recarregue a página ou escolha outro método de pagamento. quando o Pin.js não carrega; Pagamentos com cartão estão temporariamente indisponíveis. Tente novamente mais tarde ou escolha outro método de pagamento. quando a Pin Payments rejeita a chave secreta; Não conseguimos confirmar o seu pagamento com a Pin Payments. Verifique o seu e-mail e o extrato do cartão antes de tentar novamente, ou entre em contato conosco. quando a Pin Payments não responde. Os detalhes técnicos são gravados nas notas do pedido e no log.

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

O plugin não tem fluxo de 3-D Secure. Se a sua conta na Pin Payments exigir 3-D Secure, a cobrança fica pendente e o plugin faz o pedido falhar, então nenhum valor é debitado nessa tentativa; o cliente vê Não foi possível concluir o pagamento com cartão (é necessária verificação adicional). Tente outro cartão ou outro método de pagamento. Não há modo somente de autorização com captura posterior, nem cartões salvos, WooCommerce Subscriptions, Apple Pay ou Google Pay, nem webhooks.

Pedidos e reembolsos

Status do pedido

Processing: a Pin Payments informou uma cobrança bem-sucedida e capturada exatamente no valor e na moeda do pedido. Pedidos com somente produtos digitais para download tornam-se Concluído, o padrão do WooCommerce. A nota do pedido mostra o valor e o token da cobrança (e TEST MODE nos pagamentos de teste). O ID da transação é o token de cobrança da Pin Payments.

Failed: o cartão foi recusado, a cobrança ficou pendente (3-D Secure), a Pin Payments rejeitou a chave secreta ou a requisição. Cada tentativa com falha adiciona uma nota ao pedido com o código de erro e a mensagem da Pin Payments, mesmo quando o pedido já estava como Falhou por uma tentativa anterior. O cliente pode tentar novamente com o mesmo pedido.

Pending payment: a Pin Payments não deu uma resposta clara (tempo esgotado, erro do servidor, resposta ilegível). O pedido não é marcado como falho, porque a cobrança pode ter sido criada mesmo assim. A nota orienta você a procurar a descrição da cobrança no painel da Pin Payments antes de o cliente pagar novamente ou de o pedido ser enviado. Esse status é Aguardando pagamento.

On hold: a Pin Payments cobrou um valor ou uma moeda diferente do pedido (a nota mostra o valor esperado e o cobrado), ou a cobrança foi autorizada, mas não capturada. Verifique a cobrança no painel da Pin Payments antes de atender o pedido.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit card (Pin Payments) (o botão mostra o seu Title). Reembolsos totais e parciais são aceitos. O reembolso é enviado ao ambiente (teste ou produção) em que o pedido foi pago, por isso a chave secreta desse modo precisa estar preenchida. Uma requisição bem-sucedida adiciona uma nota ao pedido com o valor, o token de reembolso da Pin Payments e o status dele. A Pin Payments processa reembolsos de forma assíncrona, por isso o status costuma ser Pending. Se a Pin Payments rejeitar o reembolso ou não responder, o WooCommerce exibe o erro e nenhum reembolso é registrado.

Reembolsos feitos no painel da Pin Payments não são sincronizados com o WooCommerce, por isso faça-os pelo 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 > Pin Payments. 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 a sua conta na vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio dela. Libere a vaga na sua conta na vibefox.net.

Sem uma chave ativa, a Pin Payments 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. Gerentes da loja conectados ainda veem o método de pagamento, marcado como (sem licença — visível somente para administradores), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os reembolsos continuam funcionando.

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

Solução de problemas

A Pin Payments não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se as duas chaves do modo atual estão preenchidas (Test publishable key e Test secret key no modo de teste; as chaves de produção nos demais casos) e se a moeda do carrinho é uma das 14 moedas aceitas. Na página Pay for order, vale a moeda do pedido. A página de configurações exibe um erro para chaves ausentes e para moeda sem suporte.

Na finalização de compra aparece «Não conseguimos confirmar o seu pagamento»: a Pin Payments não respondeu a tempo. O pedido permanece em Aguardando pagamento, com uma nota. Procure no painel da Pin Payments uma cobrança com a descrição <store name> - Order <number> antes de o cliente pagar novamente ou de o pedido ser enviado. O plugin não procura essa cobrança automaticamente, e uma nova tentativa cria uma nova cobrança.

Os clientes veem «Pagamentos com cartão estão temporariamente indisponíveis»: a Pin Payments rejeitou a chave secreta. A nota do pedido orienta a verificar as chaves do modo atual. Chaves de teste funcionam somente no modo de teste, e as de produção somente no modo de produção.

Pedidos falham com «é necessária verificação adicional»: a sua conta na Pin Payments exige 3-D Secure, que o plugin não suporta. Peça à Pin Payments para desativar o 3-D Secure obrigatório.

Um pedido está Em espera com a nota «does not match»: a Pin Payments informou um valor ou uma moeda de cobrança diferente do pedido. Verifique a cobrança no painel da Pin Payments e reembolse ou conclua o pedido manualmente.

Não foi possível carregar o formulário seguro do cartão: o Pin.js da CDN da Pin Payments não carregou no navegador, por exemplo por causa de um bloqueador de scripts ou de um plugin de cache ou otimização que altera os scripts. Exclua a finalização de compra dessas otimizações.

O reembolso falha: leia a mensagem. Uma mensagem sobre o modo TEST ou LIVE significa que a chave secreta do modo em que o pedido foi pago está vazia. A Pin Payments não confirmou o reembolso significa que não houve resposta; verifique a cobrança no painel da Pin Payments antes de tentar de novo.

Pagamento falhou com um motivo da Pin Payments: a Pin Payments rejeitou os dados da cobrança, por exemplo um valor abaixo da cobrança mínima da moeda. O cliente vê o motivo, e a nota do pedido contém o código de erro.

Pagamentos de teste: o modo de teste usa o ambiente de teste e as chaves de teste. Use os cartões de teste da documentação para desenvolvedores da Pin Payments, por exemplo 4200 0000 0000 0000 (aprovado) ou 4100 0000 0000 0001 (recusado), com qualquer validade futura e qualquer CVC. Os pedidos mantêm o modo em que foram pagos, então os reembolsos vão para o ambiente certo depois que você trocar de modo.

Onde encontrar os erros: os erros são sempre gravados em WooCommerce > Status > Logs, origem wcp_pinpayments_gateway. Ative o Debug log para ver cada chamada à API.

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 na 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.

Para desenvolvedores: o filtro wc_ppg_supported_currencies altera a lista de moedas, e wc_ppg_icon altera o ícone na lista de métodos de pagamento do WooCommerce.

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, as opções de versão do plugin e os seus logs (arquivos de log, inclusive os rotacionados, e entradas de log no banco de dados) são removidos somente se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados de pagamento armazenados nos pedidos, como o token de cobrança da Pin Payments, nunca são excluídos. Os pedidos existentes mantêm as notas de pagamento e os IDs de transação.

A Pin Payments é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Pin Payments.