VibeFox Paysera for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Projeto Paysera: você precisa do ID do projeto e da senha do projeto (chave de assinatura) do seu projeto Paysera. Os métodos de pagamento que o cliente vê são os ativados neste projeto. Não é preciso configurar nada na Paysera para o callback: a URL dele é enviada com cada solicitação de pagamento.

Loja acessível: os pedidos recebem o status do callback da Paysera, então a sua loja precisa estar acessível pela internet, sem login, autenticação básica ou firewall que a bloqueie. O callback funciona mesmo com a loja em modo de manutenção.

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

Instalação

É um único arquivo zip com os pacotes para as duas versões do OpenCart. Extraia-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_paysera_payment-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_paysera_payment.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_paysera_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, por isso Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você 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. Localize VibeFox Paysera Payment e clique em Install (o botão verde +). O seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole a 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. Informe o Project ID e a Project password da sua conta Paysera (veja Configuração).

5. Opcional: ative Allow test payments no projeto Paysera e Test payments na extensão para testar o fluxo sem cobrar dinheiro. Desative antes de vender.

6. Ative Enable/Disable e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_paysera_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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. Localize VibeFox Paysera Payment, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença, o ID e a senha do projeto e as configurações de teste como nos passos 3 a 6 do OpenCart 3. A página de configurações e os seus campos são os mesmos nas duas versões. Somente a Callback URL é diferente (veja Projeto Paysera).

Uma nova instalação começa com o método de pagamento desativado, os pagamentos de teste desativados e o ambiente Production.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Paysera Payment > 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 Paysera is hidden at checkout until the project ID and the project password are entered. enquanto um dos dois estiver faltando, e Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. enquanto os pagamentos de teste ou o sandbox estiverem ativos. Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Project ID deve conter somente dígitos, Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0 e os status de pedido precisam existir. Se alguma verificação falhar, nada é salvo e a página lista os erros.

Paysera

Enable/Disable: Enable Paysera Payment liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome 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: Paysera. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely via Paysera.

Sort Order: a posição da Paysera entre os métodos de pagamento da finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer a Paysera somente 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 a Paysera seja oferecida. Deixe em branco para oferecer a Paysera em qualquer total.

Projeto Paysera

Encontre o ID do projeto e a senha do projeto na sua conta Paysera, em Projects and activities, no seu projeto, em General project settings. A seção tem um link para a conta Paysera.

Callback URL: o endereço que a Paysera usa para confirmar cada pagamento. No OpenCart 3 ele tem este formato: https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback, e no OpenCart 4: https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback. Ele é montado a partir do endereço da vitrine da sua instalação do OpenCart. Ele é enviado automaticamente com cada pagamento, então nada precisa ser configurado na Paysera, mas ele precisa estar acessível pela internet. Os pedidos recebem o status somente desses callbacks assinados ou criptografados.

Project ID: o ID numérico do seu projeto Paysera. Somente dígitos são aceitos: qualquer outro valor gera o erro Project ID must contain digits only: the numeric ID of your Paysera project. e nada é salvo.

Project password: a senha do projeto (chave de assinatura). Ela assina as solicitações de pagamento e verifica os callbacks da Paysera. A senha salva nunca é exibida novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover a senha salva, marque Clear saved password (tick and save; an empty field keeps the saved value) abaixo do campo e clique em Save.

Testes

Test payments: envia os pagamentos em modo de teste, portanto nenhum valor é cobrado. A Paysera devolve um pagamento de teste bem-sucedido sem cobrar do cliente. Ative primeiro Allow test payments nas configurações do projeto na Paysera. Enquanto esta opção estiver ativa, os pagamentos de teste marcam os pedidos como pagos; quando estiver desativada, um pagamento de teste deixa o pedido em espera. Padrão: desligado. Enquanto estiver ativa, o cliente vê TEST MODE — no money will be charged. na etapa Confirm Order.

Environment: para onde o cliente é enviado. Mantenha Production para um projeto Paysera normal, inclusive para pagamentos de teste. Padrão: Production.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status pelo callback da Paysera. Um pagamento cancelado ou não executado deixa o pedido sem status, e o cliente pode pagar novamente. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido quando a Paysera confirma o pagamento com o valor e a moeda esperados. Padrão: Processing.

Awaiting Payment Status: o banco aceitou a ordem de pagamento, mas ainda não a executou. O pedido é marcado como pago quando a Paysera confirma o pagamento. Padrão: Pending.

On Hold Status: um pagamento de TESTE enquanto Test payments está desativado, um valor ou uma moeda diferentes, ou um pagamento feito depois de o cliente tê-lo cancelado. O pedido não é marcado como pago; uma observação explica o motivo. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled Order Status: a extensão nunca define este status; ela apenas o lê: um pagamento que chega para um pedido neste status não reabre o pedido, só adiciona uma observação. Padrão: Canceled.

Avançado

Debug log: grava os eventos de pagamento em wc_psr_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros e avisos são sempre gravados; as demais etapas, somente enquanto esta opção estiver ativa. Senhas e dados do cliente nunca são gravados. Padrão: desligado.

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

Delete data: quando ativo, desinstalar a extensão remove as configurações da extensão e o log. Os dados de pedidos (pedidos, registros de pagamento da Paysera) são sempre mantidos. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. A senha do projeto não é exportada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. A senha do projeto salva é mantida.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Paysera). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. O OpenCart cria o pedido nessa etapa, ainda sem status. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte inferior da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão cria uma solicitação de pagamento assinada com o número do pedido, o total do pedido na menor unidade da moeda do pedido, o nome, o e-mail e o endereço de cobrança do cliente, e o idioma da página da loja (lituano, letão, estoniano, russo, alemão, polonês; caso contrário, inglês). O cliente é enviado para a janela de pagamento da Paysera e escolhe ali um banco, um cartão ou outro método.

A Paysera confirma o pagamento com um callback de servidor para servidor. O pedido só é marcado como pago depois que a Paysera o confirma com um callback assinado; o retorno do cliente à loja nunca paga um pedido. Em seguida, o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque. Quando o cliente volta após o callback, é exibida a página de sucesso do pedido do OpenCart. Se o banco aceitou a ordem de pagamento mas ainda não a executou, o pedido recebe o Awaiting Payment Status e a página mostra Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Para um pedido em espera, a página mostra Your payment is being reviewed. We will contact you if anything else is needed.

Se o cliente voltar antes do callback, aparece uma página Payment confirmation que explica que o pedido será confirmado assim que a Paysera confirmar o pagamento, e oferece Check again e Back to checkout.

Se o cliente cancelar na janela da Paysera, volta à finalização de compra com a mensagem The Paysera payment was cancelled. You can try again or choose another payment method. Se a Paysera informar que o pagamento não foi executado, a mensagem é The payment was not completed. You can try again or choose another payment method. O carrinho é mantido nos dois casos. No OpenCart 4 essas mensagens aparecem acima da página de finalização de compra. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, e o OpenCart 4 atualiza o pedido da finalização de compra (uma nova tentativa paga o mesmo pedido); se outro pedido do mesmo carrinho já estiver pago, aguardando pagamento ou em espera, uma nova tentativa vai direto para a página de sucesso, em vez de gerar um segundo pagamento. Uma alteração no carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de pagamento próprio.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido foi fechado nesse meio-tempo (por exemplo, se você cancelou um pedido que aguardava o pagamento bancário), o cliente volta para a finalização de compra com a mensagem Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. O próximo Confirm Order paga um pedido novo. Se esse pedido já tinha sido pago por um carrinho anterior e o carrinho mudou desde então, o cliente é levado de volta à finalização de compra, e o próximo Confirm Order paga um novo pedido do carrinho atual. Um pedido fechado nunca é exibido como pago.

Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com Paysera payments are temporarily unavailable. Please choose another payment method. ou, para um total de pedido inválido, com This order cannot be paid via Paysera. O motivo é gravado no log.

O callback também funciona enquanto a loja está em modo de manutenção, porque o OpenCart deixa passar as requisições das extensões de pagamento (no OpenCart 4 a extensão adiciona para isso uma ação de inicialização própria, que também permite ao cliente voltar da Paysera).

A extensão não tem reembolsos pelo administrador, nenhuma escolha de banco ou método de pagamento na página de finalização de compra, nenhuma assinatura, nenhum cartão salvo e nenhum serviço de entrega ou courier da Paysera.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado para a Paysera e o callback ainda não chegou, ou o cliente cancelou, ou o pagamento não foi executado. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processing): a Paysera confirmou o pagamento com o valor e a moeda correspondentes. Uma observação mostra a solicitação e o método de pagamento, marcados como (TEST — no money charged) nos pagamentos de teste.

Awaiting Payment Status (padrão Pending): a Paysera aceitou a ordem de pagamento, mas o banco ainda não a executou. O pedido passa para Order Status After Payment quando a Paysera confirma o pagamento.

On Hold Status (padrão Pending): o pagamento precisa de análise manual. O valor ou a moeda pagos diferem do total do pedido; um pagamento de TESTE chegou com Test payments desativado (nenhum valor foi cobrado); ou o pagamento foi confirmado depois que o cliente o cancelou. A observação explica isso, e a aba do pedido pede que você verifique o pagamento na sua conta Paysera e, depois, coloque o pedido no status de pago ou cancele-o e estorne o pagamento na Paysera. Um pagamento correto posterior para o mesmo pedido o marca como pago.

Cancelled Order Status (padrão Canceled): um pagamento confirmado depois para um pedido cancelado não altera o status dele. Uma observação pede que você restaure o pedido (colocando-o no status de pago) ou estorne o pagamento na Paysera. Se o método de pagamento do pedido não for mais a Paysera, um pagamento confirmado apenas adiciona uma observação.

Se chegar outro pagamento bem-sucedido para um pedido que já está pago, ou para outro pedido de um carrinho já pago, o pedido pago não é alterado, e uma observação pede que você estorne o duplicado na sua conta Paysera. Os demais status da Paysera (pagamento não executado, informações adicionais) apenas adicionam uma observação. As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Paysera Payment

Em Sales > Orders, abra um pedido pago com a Paysera. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Paysera Payment mostra o Paysera order ID (o número do pedido e a tentativa), o Paysera request ID, o Environment e uma marca TEST payment, o Status do pagamento, os valores Requested / paid, o Payment method e as Notes da extensão. Para um pedido em espera, ela mostra o que verificar. A aba apenas exibe informações e é mostrada aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos pelo administrador não são suportados: o protocolo da janela de pagamento da Paysera não tem API de reembolso. Faça os reembolsos na sua conta Paysera. Quando a Paysera informa um reembolso, uma observação com o valor reembolsado é adicionada ao pedido, e o status do pedido não muda. Registre o reembolso no OpenCart manualmente, se necessário. As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Paysera.

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 Paysera Payment é o primeiro bloco da página Extensions > Extensions > Payments > VibeFox Paysera Payment > 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 ficam a linha Product: opencart-payment-paysera e o link Manage licenses and domains in your account, que abre a sua conta 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 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, a extensão continua funcionando com o último status conhecido.

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

Sem uma chave ativa, a Paysera não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado com (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 enxerga o login do painel, 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. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados pelo callback.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente automaticamente ao abrir o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A Paysera não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se Project ID e Project password estão preenchidos. A página de configurações mostra um aviso enquanto algum deles estiver faltando. 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 pagamento foi feito, mas o pedido continua sem status: o pedido recebe o status do callback da Paysera, não do retorno do cliente. Verifique se a sua loja está acessível pela internet na Callback URL mostrada nas configurações (não atrás de login, autenticação básica ou firewall) e veja o campo Log na página da extensão.

O callback responde Invalid signature: a Project password não corresponde ao projeto, ou o callback não veio da Paysera. Copie a senha do projeto novamente. Se você trocou o projeto ou a senha, os pagamentos iniciados antes da mudança não podem mais ser verificados.

O callback responde Project ID mismatch: o Project ID das configurações é diferente do projeto que fez o pagamento.

O callback responde Order not found: o pedido do callback não tem um pagamento Paysera nesta loja, por exemplo porque o pagamento foi iniciado em outra loja com o mesmo projeto.

O callback responde Gateway not configured, Busy ou Temporary error: o ID ou a senha do projeto está vazio, outro callback do mesmo carrinho ainda está em execução, ou não foi possível definir o status do pedido. A Paysera tenta o callback novamente. Ative Debug log para ver o motivo.

A Paysera recusa a janela de pagamento ou diz que o projeto não existe: verifique Environment. Um projeto Paysera normal funciona somente com Production; o Sandbox exige um projeto criado no ambiente sandbox da Paysera.

O pagamento de teste não paga o pedido: um pagamento de TESTE só paga um pedido enquanto Test payments estiver ativo. Caso contrário, o pedido é colocado em espera com uma observação informando que nenhum valor foi cobrado. Ative também Allow test payments no projeto da Paysera.

Um pedido está em espera com uma observação sobre divergência de valor ou moeda: a Paysera confirmou um pagamento cujo valor ou moeda é diferente do total do pedido. Compare o pagamento na sua conta Paysera e aceite o pedido ou estorne o pagamento manualmente.

O cliente vê Paysera payments are temporarily unavailable: consulte o campo Log. O ID ou a senha do projeto podem estar vazios, ou um dos endereços da loja enviados à Paysera tem mais de 255 caracteres.

O cliente vê This payment method is not available. Please reload the checkout page.: a sessão de finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desativado nesse meio-tempo. O cliente recarrega a finalização de compra.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Paysera Payment. 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 padrões em uma nova instalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixam passar o callback e o retorno do cliente em modo de manutenção). Se Delete data estiver ativo, as demais configurações (título, descrição, ID e senha do projeto, testes, log) e o log são excluídos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. Os registros de pagamento da Paysera são sempre mantidos. Os pedidos existentes mantêm as suas observações de pagamento.

Para remover também os arquivos da extensão no OpenCart 4, depois da desinstalação acesse Extensions > Installer, clique em Uninstall (o botão laranja −) ao lado de VibeFox Paysera Payment na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

Paysera é uma marca de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Paysera.