VibeFox Pin Payments for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.

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, para o ambiente de teste. Nenhum segredo de webhook é necessário: o módulo não usa webhooks. Os dados do cartão são enviados do navegador do cliente diretamente à Pin Payments pelo Pin.js e nunca chegam à sua loja, por isso a loja se enquadra no PCI SAQ A-EP.

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

Instalação

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

2. Quando o upload terminar, clique em Configure, ou encontre depois VibeFox Pin Payments 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. No painel da Pin Payments, abra Account > API Keys e copie suas chaves de teste para Test publishable key e Test secret key. Mantenha Test mode ativado, ative Enable/Disable e clique em Save.

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

Na instalação, o módulo cria o status de pedido Pin Payments payment on hold. O PrestaShop oferece um novo módulo de pagamento para as moedas, grupos de clientes e países ativos no momento da instalação. Você pode alterar isso em Payment > Preferences; países ativados depois precisam ser marcados ali.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Pin Payments 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 um aviso enquanto o modo de teste estiver ativado, um erro quando a chave publicável ou a chave secreta do modo atual está vazia, e um erro quando a Pin Payments não oferece suporte à moeda padrão da loja (com a lista de moedas suportadas). Sem as duas chaves do modo atual, o método de pagamento fica oculto na finalização de compra. Um Title vazio não é salvo: a página mostra Enter a title for the payment method.

Pin Payments

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

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit card (Pin Payments). Obrigatório.

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

Chaves de API

Encontre suas chaves no painel da Pin Payments, em Account > API Keys. As chaves de teste funcionam somente com a API de teste, e as chaves 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: 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 TEST MODE — no real charges will be made. abaixo do método de pagamento. Quando está desativado, são usadas a API de produção 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.

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.

Espaços em volta das chaves são removidos. Chaves secretas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.

Clear saved secrets: marque uma chave secreta e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Avançado

Debug log: grava em logs/wc_ppg_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. 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.

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 as configurações do gateway e o log são removidos. Os dados de pagamento dos pedidos (cobranças e reembolsos) e o status de pedido Pin Payments payment on hold são sempre mantidos. Padrão: desativado.

Finalização de compra

O método de pagamento é exibido quando está ativado, as duas chaves do modo atual estão preenchidas, a moeda do carrinho é uma das 14 moedas suportadas (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) e o módulo está permitido para o carrinho em Payment > Preferences.

Na etapa de pagamento, 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. Antes do envio, o formulário 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.

Quando o cliente faz o pedido, o Pin.js envia do navegador diretamente à Pin Payments os dados do cartão e o endereço de cobrança do carrinho, e recebe um token de cartão de uso único. Somente esse token é enviado à sua loja. Em seguida, o módulo cria uma cobrança capturada pelo total do carrinho na moeda do carrinho, com o e-mail do cliente e a descrição <shop name> - Cart <cart number>. A Pin Payments responde na mesma requisição. Nenhum pedido existe antes dessa resposta.

Após uma cobrança bem-sucedida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your card payment has been received. Se o pedido foi para Pin Payments payment on hold, a página mostra Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Se a Pin Payments não responder (tempo esgotado, erro do servidor, resposta ilegível), uma cobrança pode ter sido criada mesmo assim. O pedido é então criado em Pin Payments payment on hold sem pagamento, e a página de confirmação mostra We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Enviar novamente o mesmo carrinho nunca cria uma segunda cobrança.

Apenas uma tentativa de pagamento por carrinho é executada por vez. Um segundo envio recebe This order is already being paid. Please wait a moment and check your e-mail before trying again. Um carrinho que já tem um pedido, ou uma tentativa anterior que cobrou ou pode ter cobrado o dinheiro, não é cobrado novamente; o pedido é criado a partir dessa tentativa. Um token de cartão pode ser usado uma única vez: após uma tentativa falha, ou quando o cliente altera os dados do cartão, um novo token é criado.

Quando o pagamento falha, nenhum pedido é criado. O cliente permanece na etapa de pagamento, o carrinho é mantido e uma destas mensagens é exibida: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: com o motivo informado pela Pin Payments para os dados rejeitados; Your card details have expired. Please enter them again and retry. quando o token não pode ser usado; The secure card form could not be loaded. Please reload the page or choose another payment method. quando o Pin.js não carrega; Card payments are temporarily unavailable. Please try again later or choose another payment method. quando a Pin Payments rejeita a chave secreta; Your payment could not be processed. Please try again or choose another payment method. para outros erros. O motivo técnico é gravado no log.

O módulo não tem fluxo de 3-D Secure. Se a sua conta na Pin Payments exigir 3-D Secure, a cobrança fica pendente, nenhum pedido é criado e o cliente vê Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Não há modo somente de autorização com captura posterior, nem cartões salvos, assinaturas, Apple Pay ou Google Pay, nem webhooks.

Pedidos e reembolsos

Status do pedido

No order yet: o cartão foi recusado, a cobrança precisava de 3-D Secure, ou o cliente não pagou. Existe apenas o carrinho.

Payment accepted: a Pin Payments informou uma cobrança bem-sucedida e capturada exatamente no valor e na moeda do carrinho. O pagamento é registrado com o token de cobrança da Pin Payments como ID da transação, e uma nota mostra o valor e o token de cobrança (e TEST MODE para pagamentos de teste).

Pin Payments payment on hold: a cobrança precisa da sua análise. A nota explica o motivo: a Pin Payments cobrou um valor ou uma moeda diferentes do carrinho (o pagamento do valor cobrado é registrado), o carrinho foi alterado durante o pagamento, a cobrança está autorizada mas não capturada (capture-a no painel da Pin Payments e depois altere o pedido para Pagamento aceito), ou a Pin Payments não deu uma resposta clara (nenhum pagamento é registrado; procure a descrição da cobrança no painel da Pin Payments antes de enviar o pedido).

Refunded: a cobrança foi totalmente reembolsada pelo módulo.

Se uma segunda cobrança for feita para um carrinho que já tem pedido, o pedido não é alterado. Uma nota pede que você verifique e reembolse no painel da Pin Payments.

Bloco da Pin Payments

A página do pedido mostra um bloco Pin Payments com um selo Test mode para pagamentos de teste, o token de cobrança, o status, a bandeira do cartão e os últimos quatro dígitos, o valor cobrado, o total do pedido e o valor reembolsado, a Description at Pin Payments, o histórico de reembolsos e as Pin Payments notes do pedido.

Reembolsos

No bloco Pin Payments, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Pin Payments. Confirme a pergunta Refund this amount through Pin Payments? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa da permissão para editar pedidos. Os reembolsos ficam limitados ao valor e à moeda que a Pin Payments de fato cobrou; portanto, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente pagou, e não o total do pedido. 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. A Pin Payments processa os reembolsos de forma assíncrona, então o status costuma ser pendente. Uma solicitação bem-sucedida é adicionada ao histórico de reembolsos e às notas, com o token de reembolso da Pin Payments e seu status. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Se a Pin Payments rejeitar o reembolso ou não responder, o bloco mostra o erro e nenhum reembolso é registrado.

Quando nenhuma cobrança está registrada para o pedido (a Pin Payments não deu uma resposta clara), o bloco não mostra o formulário de reembolso e informa qual descrição procurar no painel da Pin Payments.

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 Pin Payments. Reembolsos feitos no painel da Pin Payments não são sincronizados de volta ao PrestaShop, então faça-os pela página do pedido.

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 Pin Payments Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, acima das configurações. Digite 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 ficam a linha Product: presta-payment-pinpayments e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure do 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 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, o módulo continua funcionando com o último status conhecido.

Uma chave funciona em um único 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 Pin Payments 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 vitrine do PrestaShop não sabe que você está conectado ao 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. Os pedidos existentes não são afetados: os reembolsos de pedidos pagos antes continuam funcionando.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem a 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 informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

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; caso contrário, as chaves de produção) e se a moeda do carrinho é uma das 14 moedas suportadas. 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. A página de configurações mostra um erro para chaves ausentes e para uma moeda da loja sem suporte.

O pagamento foi feito, mas o pedido está em Pin Payments payment on hold: leia as notas no bloco Pin Payments (veja Status do pedido). Se a Pin Payments não deu uma resposta clara, procure no painel da Pin Payments uma cobrança com a descrição <shop name> - Cart <cart number>, depois envie o pedido ou reembolse a cobrança no painel.

O cliente vê Your payment was received, but the order could not be completed automatically: o cartão foi cobrado, mas o PrestaShop não conseguiu criar o pedido (por exemplo, porque o módulo foi desativado nesse meio tempo). O motivo está no log. O cliente é orientado a não pagar novamente; enviar o mesmo carrinho de novo cria o pedido sem uma nova cobrança.

Os clientes veem Card payments are temporarily unavailable: a Pin Payments rejeitou a chave secreta, ou a chave do modo atual está ausente. Chaves de teste funcionam somente no modo de teste, e chaves de produção somente no modo de produção. O log mostra o motivo.

Os pedidos falham com additional verification is required: sua conta na Pin Payments exige 3-D Secure, que o módulo não suporta. Peça à Pin Payments para desativar o 3-D Secure obrigatório.

O formulário seguro de cartão não pôde ser carregado: o Pin.js do CDN da Pin Payments não carregou no navegador, por exemplo por causa de um bloqueador de scripts ou de um módulo que combina ou altera scripts. Exclua a finalização de compra dessas otimizações.

A Pin Payments não respondeu: o token do cartão não foi criado no navegador em 30 segundos. O cliente pode verificar a conexão e tentar novamente; nada foi cobrado.

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 para a moeda. O cliente vê o motivo, e o log tem o código do erro.

O reembolso falha: leia a mensagem no bloco. Uma mensagem sobre o modo TEST ou LIVE significa que a chave secreta do modo em que o pedido foi pago está vazia. Pin Payments did not confirm the refund significa que não chegou nenhuma resposta; verifique a cobrança no painel da Pin Payments antes de tentar de novo. at most mostra o valor que ainda pode ser reembolsado da cobrança.

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 data de 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ê troca de modo.

Onde encontrar os erros: os erros são sempre gravados no log; veja o campo Log na página do módulo. Ative o Debug log para ver cada chamada à API.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Pin Payments Gateway e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As cobranças e reembolsos da Pin Payments e o status de pedido Pin Payments payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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