VibeFox Satispay for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior com a extensão OpenSSL. A extensão gera as chaves RSA com o OpenSSL.

Moeda: EUR. A Satispay cobra somente em euros. A moeda EUR precisa estar habilitada em System > Localisation > Currencies, e o método de pagamento só é exibido enquanto o cliente tiver EUR selecionado.

Conta Satispay: uma conta Satispay Business. Você não copia nenhuma chave de API: a extensão se conecta com um código de ativação único que você gera no Satispay Business Dashboard (veja Configuration). Para testes, você precisa de uma conta sandbox da Satispay, que solicita à Satispay para desenvolvedores.

Loja pública: sua loja precisa estar acessível pela internet, para que a Satispay possa chamá-la quando um pagamento mudar. Nada precisa ser configurado na Satispay para isso.

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_satispay_gateway-oc3-(version).ocmod.zip, e o pacote do OpenCart 4, wcp_satispay_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. Noadmin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_satispay_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 Satispay Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter o 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 sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja License key).

4. Escolha o ambiente: ative Sandbox Mode para os testes; deixe-o desativado para pagamentos reais.

5. Cole um código de ativação desse ambiente em Activation Code e clique em Save. O campo Status então mostrará Connected com o Key ID.

6. Ative Enable/Disable e clique em Save. Teste um pagamento no sandbox e, em seguida, desative Sandbox Mode e conecte o ambiente de produção com um código de ativação de produção.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_satispay_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 Satispay 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, escolha o ambiente e conecte-o com um código de ativação, como nas etapas 3 a 6 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de callback é diferente (veja Notificações de pagamento).

Uma nova instalação começa com o método de pagamento desativado e o ambiente de produção selecionado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Satispay Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando o método de pagamento está ativado, mas o ambiente em uso não está conectado (nesse caso, o método de pagamento fica oculto no checkout), e quando a moeda padrão da loja não é EUR (nesse caso, o método de pagamento só aparece enquanto o cliente tiver EUR selecionado). 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, Sort Order deve ser um número inteiro (números 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 precisam existir. Se um valor estiver errado, nada é salvo e o código de ativação não é enviado.

Checkout

Enable/Disable: Enable Satispay payment liga ou desliga o método de pagamento. Default: off.

Title: o nome do método de pagamento que o cliente vê no checkout. Também é o nome do método de pagamento salvo no pedido. Default: Satispay. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

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

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

Total: o total do checkout, na moeda padrão da loja, que um pedido precisa atingir antes de a Satispay ser oferecida: um número igual ou maior que 0. Deixe em branco para oferecer a Satispay em qualquer valor total.

Conexão com a Satispay

Status: o estado dos dois ambientes, por exemplo Live: Connected com o Key ID ou Sandbox: Not connected, e qual ambiente está in use. Enquanto o ambiente em uso não estiver conectado, o campo diz Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: usa o ambiente sandbox (de testes) da Satispay. Pagamentos no sandbox não são cobrados. Default: off. Sandbox e produção têm chaves separadas: conecte cada ambiente com um código de ativação desse mesmo ambiente. Enquanto o sandbox estiver em uso, o cliente vê Sandbox mode: no real money is charged. na etapa Confirm Order.

Activation Code: para conectar o ambiente selecionado acima, cole um novo código de ativação de 6 caracteres e clique em Save. Os códigos de produção são gerados no Satispay Business Dashboard, na seção Online shop (o campo tem um link para lá). Os códigos sandbox vêm com uma conta sandbox da Satispay. O código é usado uma única vez e não é armazenado. Deixe o campo vazio para manter a conexão atual.

Ao salvar com um código, as configurações são salvas primeiro. Depois, a extensão cria um par de chaves RSA, envia a chave pública e o código para a Satispay e armazena o Key ID e as chaves do ambiente em uso. As chaves privadas nunca são exibidas nem exportadas. Em caso de sucesso, a página mostra, por exemplo, Satispay Live connected. Key ID: seguido do ID. Se a Satispay rejeitar o código, a página mostra Satispay activation failed: com a mensagem da Satispay e pede que você verifique se o código é deste ambiente e se ainda não foi usado; a conexão atual é mantida. Um código que não tenha de 4 a 64 letras e dígitos é recusado antes de qualquer envio. Salvar um novo código para um ambiente substitui a conexão anterior dele.

Notificações de pagamento

Nada a configurar na Satispay. Cada pagamento traz sua própria URL de callback, que a Satispay chama quando o pagamento muda, e a extensão relê o pagamento a partir da API da Satispay antes de alterar um pedido. O campo Callback URL mostra um exemplo desta URL. No OpenCart 3, ela tem a forma https://your-store/index.php?route=extension/payment/wcp_satispay_gateway/callback&satispay_p_order={order}&payment_id={uuid}; no OpenCart 4, a forma é https://your-store/index.php?route=extension/wcp_satispay_gateway/payment/wcp_satispay_gateway.callback&satispay_p_order={order}&payment_id={uuid}. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. A URL precisa ser acessível pela internet: não pode haver firewall nem autenticação básica na frente dela. O modo de manutenção do OpenCart não a bloqueia. Se o callback não conseguir chegar à sua loja, o pedido é confirmado quando o cliente voltar.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente, missing order). O pedido só recebe um status depois que a Satispay aceita o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status atribuído depois que o pagamento foi aceito. Default: Processing.

Satispay Payment On Hold Status: o dinheiro foi recebido, mas o pedido precisa de revisão (veja Order statuses). Default: 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 página do pedido. Default: Refunded.

Avançado

Debug log: grava as chamadas à API e os eventos de pagamento em satispay_p_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 satispay_p_debug.old.log.php. Chaves, código de ativação e dados dos clientes não são registrados. Os erros são sempre registrados, mesmo quando esta opção está desativada. Default: off.

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

Delete data on uninstall: quando ativada, desinstalar a extensão remove as configurações do gateway, as chaves da Satispay dos dois ambientes e o log. Os pagamentos e reembolsos da Satispay salvos para os pedidos são sempre mantidos. Default: off.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves da Satispay não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. A conexão com a Satispay é mantida.

Checkout

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Satispay). Na etapa Confirm Order, o cliente vê a sua descrição e a nota You will be redirected to the Satispay page: scan the QR code with the Satispay app or confirm the payment on your phone. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria um pagamento na Satispay pelo total do pedido em euros, com o número do pedido como referência, e envia o cliente para a página de pagamento da Satispay. No computador, o cliente lê o QR code com o aplicativo Satispay. No celular, o cliente confirma o pagamento no aplicativo. 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, e clica em Confirm Order na parte inferior da página de finalização de compra.

Depois do pagamento, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Satispay confirma: a extensão lê o pagamento pela API da Satispay, verifica se ele foi criado para este pedido e compara o status, o valor (em centavos) e a moeda com o pedido. Isso acontece tanto quando a Satispay chama a URL de callback quanto quando o cliente retorna, o que vier primeiro. Depois, o pedido recebe o status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se a Satispay ainda não tiver confirmado o pagamento quando o cliente voltar, uma página Payment confirmation mostra Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. e um botão Check again. O callback define o status do pedido assim que chega.

Se o cliente sair da página da Satispay sem pagar, a extensão cancela o pagamento na Satispay, para que a página abandonada não possa mais ser paga. O cliente volta ao checkout com a mensagem Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. A mesma mensagem aparece quando o cliente recusa o pagamento no aplicativo. O carrinho é mantido.

No OpenCart 3, um novo pedido é criado sempre que a etapa Confirm Order é exibida. No OpenCart 4, o pedido da finalização de compra é mantido e atualizado; por isso, depois de um pagamento cancelado, o mesmo pedido é pago com um novo pagamento da Satispay. Antes de criar um novo pagamento na Satispay, os pagamentos anteriores do carrinho são verificados: um pagamento pendente é cancelado na Satispay e, se algum já tiver sido pago, ele confirma o seu pedido; nenhum segundo pagamento é feito e o cliente vai direto para a página de sucesso.

No OpenCart 4, a mensagem sobre o pagamento cancelado aparece acima da página de finalização de compra. Se o pedido da finalização de compra tiver sido fechado pela loja nesse meio-tempo (por exemplo, cancelado ou reembolsado), ou já estiver pago mas o carrinho tiver mudado desde então, inclusive com uma nova quantidade, o cliente é enviado de volta à finalização de compra com Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. acima da página de finalização de compra, e o próximo Confirm Order paga um novo pedido.

Se o pagamento não puder ser iniciado, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão: Satispay is not available at the moment. Please choose another payment method. quando a Satispay rejeita as chaves; Satispay supports EUR currency only. para um pedido em outra moeda; ou Unable to create the Satispay payment. Please try again or choose another payment method. para outros erros. O motivo é gravado no log.

O callback e o retorno do cliente funcionam com a loja em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização para elas.

A extensão aceita apenas pagamentos únicos em euros. Não há assinaturas, métodos de pagamento salvos, pré-autorizações ou vale-refeição. Não existe verificação programada dos pagamentos pendentes: se nem o callback da Satispay nem o retorno do cliente chegarem à sua loja, o pedido fica sem status e o pagamento fica visível no Satispay Dashboard.

Pedidos e reembolsos

Status do pedido

No status (missing order): o cliente foi enviado para a Satispay e não pagou, ou a Satispay ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders. Um pagamento cancelado na Satispay deixa o pedido sem status, e o cliente pode pagar de novo.

Order Status After Payment (default Processing): o pagamento foi aceito. Uma nota mostra o pagamento da Satispay, o valor e como ele foi verificado (callback, redirecionamento ou checkout).

Satispay Payment On Hold Status (default Pending): a Satispay informou um valor ou uma moeda diferentes do total do pedido, ou o pagamento foi aceito depois que o pedido recebeu outro status (por exemplo, cancelado). A nota explica isso. Verifique o pagamento no Satispay Dashboard e, então, atenda o pedido ou reembolse o pagamento. Se outro pagamento do mesmo carrinho, com o valor correto, for aceito depois, o pedido passa para Order Status After Payment.

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

Se um segundo pagamento for aceito para um pedido que já está pago, ou para outro pedido do mesmo carrinho, o pedido pago não é alterado. Uma nota pede que você reembolse o pagamento duplicado pelo Satispay Dashboard.

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

VibeFox Satispay Gateway tab

Em Sales > Orders, abra um pedido pago com a Satispay. Na parte de baixo da página do pedido, ao lado de History e Additional, a aba VibeFox Satispay Gateway mostra o Satispay payment ID com o rótulo Sandbox para pagamentos sandbox, o Status do pagamento, os valores Paid / refunded, o formulário de reembolso, o histórico de Refunds, a lista Satispay payments of this cart com cada tentativa de pagamento, o pedido e o ambiente dela, e as Satispay notes do pedido. A aba é exibida para usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox Satispay Gateway, informe o Amount (o valor ainda não reembolsado já vem preenchido), opcionalmente um Reason (optional), e clique em Refund via Satispay. Confirme a pergunta Refund this amount through Satispay? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa do direito de modificar a extensão (definido em System > Users > User Groups). Os reembolsos ficam limitados ao valor que a Satispay cobrou pelo pagamento; por isso, depois de 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 para o ambiente em que o pagamento foi feito (produção ou sandbox), então esse ambiente precisa continuar conectado. Um reembolso só conta como feito quando a Satispay o aceita: um reembolso bem-sucedido é adicionado ao histórico e às notas, com o ID do reembolso da Satispay e o motivo. Se a Satispay não aceitar o reembolso, 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 os produtos ao estoque, como uma mudança manual de status. Um reembolso parcial não altera o status. Os reembolsos estão disponíveis depois que a Satispay aceitou o pagamento.

Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Satispay. Reembolsos feitos no Satispay Dashboard não são registrados no OpenCart. Atualize o pedido manualmente, se necessário.

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 Satispay Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Satispay 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-satispay 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 admin (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, 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 em vibefox.net.

Sem uma chave ativa, a Satispay não é exibida aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador conectado ao admin 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 admin, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do admin: 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 Satispay não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ligado, se o ambiente em uso está conectado (o campo Status mostra Connected para ele) e se o cliente tem EUR selecionado. 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 quando a Satispay chama a sua loja ou quando o cliente retorna. Verifique se a sua loja está acessível pela internet, sem firewall ou autenticação básica na frente da URL de callback, e ative Debug log para ver os callbacks no campo Log. O pagamento fica visível no Satispay Dashboard.

O callback responde Payment status unavailable, retry later. ou Not configured.: a extensão não conseguiu ler o pagamento na Satispay, ou o ambiente do pagamento não está conectado. Nenhum pedido é alterado. A Satispay chama de novo. Verifique o status da conexão e o log.

O callback responde Busy, retry later.: o carrinho estava sendo confirmado por outra requisição ao mesmo tempo, ou o status do pedido não pôde ser definido. A Satispay chama de novo. O log mostra o motivo.

O callback responde Unknown payment. ou Missing or invalid payment_id.: o pagamento não foi criado por esta loja para este pedido, ou a requisição não é um callback da Satispay. Nada é alterado.

A ativação falha: códigos de ativação só podem ser usados uma vez. Verifique se o código pertence ao ambiente selecionado em Sandbox Mode (um código de produção para produção, um código sandbox para o sandbox), gere um novo código e salve de novo. Se a página disser que não foi possível gerar um par de chaves RSA, peça à sua hospedagem para ativar a extensão OpenSSL do PHP. Se a Satispay não puder ser acessada, verifique se o seu servidor consegue abrir conexões HTTPS de saída.

A Satispay sumiu do checkout depois de trocar de sandbox para produção: sandbox e produção usam chaves diferentes. Cole um código de ativação de produção com Sandbox Mode desligado e salve.

O cliente vê This payment method is not available.: o checkout não corresponde mais ao pedido, ou o método de pagamento foi desligado nesse meio tempo. O cliente recarrega o checkout.

O pedido está no status de revisão depois do pagamento: leia as notas na aba VibeFox Satispay Gateway (veja Order statuses), verifique o pagamento no Satispay Dashboard e, então, atenda o pedido ou reembolse o pagamento.

Não há formulário de reembolso na aba: a aba informa o motivo: o pedido não tem um pagamento aceito pela Satispay, está totalmente reembolsado, o seu grupo de usuários não tem o direito de modificar a extensão, ou o ambiente do pagamento não está mais conectado.

O reembolso falha porque o ambiente não está mais conectado: o pagamento foi feito em produção ou em sandbox, e esse ambiente não tem mais chaves. Conecte-o de novo com um código de ativação, ou reembolse o pagamento pelo Satispay Dashboard.

O reembolso falha com Satispay did not accept the refund: a Satispay retornou um status diferente de accepted. O OpenCart não registrou o reembolso, e uma nota informa isso. Verifique no Satispay Dashboard.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Satispay 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. No OpenCart 4, também são removidos o evento da extensão e a sua ação de inicialização, que deixa o callback e o retorno do cliente passarem no modo de manutenção. Se Delete data on uninstall estiver ativado, as demais configurações do gateway (título, descrição, modo sandbox, logs), as chaves da Satispay dos dois ambientes e o log são removidos. Se estiver desativado, eles são mantidos para uma reinstalação posterior, inclusive a conexão com a Satispay. Os pagamentos e reembolsos da Satispay salvos para os pedidos são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados depois de uma reinstalação, quando o ambiente estiver conectado de novo. Os pedidos existentes mantêm as suas notas de pagamento.

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

A Satispay é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Satispay.