VibeFox MakeCommerce 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.

Acesso à internet para a sua loja: a MakeCommerce envia as notificações de pagamento para a sua loja, por isso o site precisa estar acessível pela internet. Um firewall ou a autenticação básica podem bloqueá-las. O modo de manutenção não as bloqueia: 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 (startup action) para elas.

Conta na MakeCommerce: você precisa do Shop ID e da Secret key do MakeCommerce Merchant Portal (Settings > API). Os ambientes de teste e de produção têm contas e chaves separadas. Quais métodos de pagamento e moedas estão disponíveis é definido pelo seu contrato com a MakeCommerce. Moedas com três casas decimais, como KWD ou BHD, não são oferecidas.

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

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote para OpenCart 3 wcp_makecommerce_payment-oc3-(version).ocmod.zip e o pacote para OpenCart 4 wcp_makecommerce_payment.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. Nopainel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_makecommerce_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, portanto 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. Localize VibeFox MakeCommerce Payment e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com 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 Chave de licença).

4. Informe o Shop ID e a Secret key do ambiente de teste e, para pagamentos reais, as chaves de produção (veja Configuração). Não é preciso configurar nada no Merchant Portal.

5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test mode ativado e depois desative-o para receber pagamentos reais.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_makecommerce_payment.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, escolha o tipo Payments, encontre VibeFox MakeCommerce Payment, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as chaves da MakeCommerce como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Apenas as URLs de callback são diferentes (veja Notificações de pagamento).

Uma nova instalação começa com o método de pagamento desativado e o modo de teste ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox MakeCommerce Payment > 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 mostra Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. enquanto o modo de teste estiver ativado. Ela avisa quando o método está ativado, mas o Shop ID ou a Secret key do ambiente atual está vazio (nesse caso o método fica oculto no checkout), e quando a moeda padrão da loja não pode ser cobrada pela MakeCommerce (nesse caso o método fica oculto para pedidos nessa moeda). Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode ficar vazio nem ter mais de 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 cada status de pedido precisa existir. Se algum campo estiver errado, nada é salvo e a página indica o campo. Espaços são removidos dos Shop IDs e das chaves ao salvar.

MakeCommerce

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

Title: o nome do método de pagamento que o cliente vê no checkout. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Bank link or card (MakeCommerce). Obrigatório, até 128 caracteres.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

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

Geo Zone: oferecer a MakeCommerce apenas 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 do checkout, na moeda padrão da loja, que um pedido precisa atingir para que a MakeCommerce seja oferecida. Deixe vazio para oferecer a MakeCommerce em qualquer valor.

Conta na MakeCommerce

O Shop ID e a Secret key ficam no MakeCommerce Merchant Portal, em Settings > API. O portal de teste e o de produção têm contas e chaves separadas. A seção tem links para os dois portais e para a página de cadastro da MakeCommerce.

Test mode: usa o ambiente de teste da MakeCommerce (nenhum dinheiro real é cobrado). Novos pagamentos são criados no ambiente selecionado, com as chaves dele. Cada pedido guarda o ambiente em que foi pago: as consultas de status e os reembolsos sempre vão para esse ambiente. Enquanto estiver ativado, os clientes veem TEST MODE — MakeCommerce test environment, no real money is charged. na etapa Confirm Order. Padrão: ativado.

Test Shop ID: o Shop ID da sua conta de teste, no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: a Secret key da sua conta de teste. Ela assina e verifica as mensagens de pagamento.

Live Shop ID: o Shop ID da sua conta de produção, no mesmo formato.

Live Secret key: a Secret key da sua conta de produção.

As Secret keys salvas nunca mais são exibidas. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Notificações de pagamento

Não é preciso configurar nada no Merchant Portal. Callback URLs mostra, apenas como referência, o endereço para o retorno ou cancelamento do cliente e o endereço das notificações de pagamento. Eles são montados a partir do endereço da loja na sua instalação do OpenCart, por exemplo https://your-store/index.php?route=extension/payment/wcp_makecommerce_payment/notification no OpenCart 3 e https://your-store/index.php?route=extension/wcp_makecommerce_payment/payment/wcp_makecommerce_payment.notification no OpenCart 4. Cada transação recebe suas próprias URLs de retorno, cancelamento e notificação, baseadas nesses endereços com o número do pedido e uma chave adicionada. A MakeCommerce envia uma mensagem assinada para a URL de notificação (de servidor para servidor) e, pelo navegador do cliente, para a URL de retorno ou de cancelamento. A assinatura é verificada com a Secret key do ambiente em que a transação foi criada. Mensagens sem assinatura válida são rejeitadas.

A extensão processa estes status de transação da MakeCommerce:

O pagamento também é confirmado quando o cliente volta para a loja. Se o cliente voltar sem uma mensagem assinada, a extensão consulta o status na API da MakeCommerce.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele recebe um status somente depois que a MakeCommerce confirma o pagamento (notificação assinada ou retorno assinado do cliente, verificado pela API da MakeCommerce). Cada campo abaixo lista os status de pedido do seu OpenCart.

Order Status After Payment: o status depois de um pagamento verificado da MakeCommerce. Padrão: Processando.

Payment On Hold Status: o pagamento precisa de revisão manual: o valor ou a moeda pagos diferem do pedido, a transação ainda não está final na MakeCommerce, ou o dinheiro chegou para um pedido cancelado. Uma nota explica o motivo. Padrão: Pendente, porque o OpenCart não tem um status Em espera. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Cancelled Order Status: o status que significa «cancelado» na sua loja. Um pagamento da MakeCommerce que chega para um pedido assim coloca o pedido em espera. A extensão nunca define esse status sozinha. Padrão: Cancelado.

Refunded Status: definido depois que o pagamento é totalmente reembolsado pela página do pedido. Padrão: Reembolsado.

Avançado

Debug log: registra as chamadas à API e as notificações de pagamento no arquivo wc_mkc_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros são sempre registrados. Chaves e dados 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: quando ativado, desinstalar a extensão remove as configurações da extensão e o log. Os pedidos e os dados de pagamento da MakeCommerce são sempre mantidos. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. Shop IDs e Secret keys não são exportados.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. Os Shop IDs e as chaves salvos são mantidos.

Checkout

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Bank link or card (MakeCommerce)). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma transação na MakeCommerce pelo total do pedido na moeda do pedido e envia o cliente para a página de pagamento da MakeCommerce. Ali o cliente escolhe um link bancário ou um cartão. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose no bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização de compra. O e-mail e o país do cliente são passados para a MakeCommerce, e a página abre no idioma da loja quando a MakeCommerce o oferece (estoniano, inglês, letão, lituano, finlandês, russo, alemão, polonês); caso contrário, em inglês.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a MakeCommerce confirma: pela notificação assinada ou pelo retorno assinado do cliente, com verificação da transação pela API da MakeCommerce. Depois disso, o pedido recebe o status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização de estoque, e o cliente vê a página de sucesso do pedido do OpenCart com Your MakeCommerce payment has been received. Se o pedido tiver entrado no status de revisão, a página mostra Your MakeCommerce payment was received and is being reviewed by the store.

Se o pagamento estiver aprovado, mas ainda não concluído, se o pedido estiver sendo confirmado por outra requisição no mesmo momento, ou se a MakeCommerce não puder ser acessada, uma página Payment confirmation mostra We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. com os botões Check again e Back to checkout. Check again pede à MakeCommerce o status das últimas transações do pedido. A notificação define o status do pedido assim que o pagamento é concluído.

Se o cliente cancelar na página da MakeCommerce, ou se o pagamento expirar ou falhar, o cliente volta ao checkout com uma mensagem, por exemplo The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. ou The payment was not completed. Please try again or choose another payment method. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. O carrinho é mantido, e o cliente pode pagar de novo. Cada tentativa é uma nova transação da MakeCommerce (o OpenCart 3 também cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 mantém um único pedido para a finalização de compra e paga o mesmo pedido de novo). Antes de uma nova transação, as tentativas abertas do mesmo carrinho são verificadas na MakeCommerce: se alguma já estiver paga, o cliente vai direto para a página de sucesso. Um link de pagamento antigo do mesmo carrinho continua funcionando, mas o carrinho nunca é pago em dois pedidos: um pagamento atrasado de um pedido antigo de um carrinho já pago apenas acrescenta uma nota ao pedido pago.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se, nesse meio-tempo, o pedido foi fechado sem pagamento (por exemplo, você o cancelou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., e o próximo clique em Confirm Order paga um novo pedido. Esse pedido não retém mais o carrinho, mesmo que tenha sido pago e depois cancelado.

Se a MakeCommerce não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. ou MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. O motivo técnico é gravado no log.

O banco ou o cartão é escolhido na página da MakeCommerce, e não no checkout da sua loja. A extensão não tem cartões salvos, pagamentos recorrentes ou assinaturas, nem envio pela MakeCommerce (pontos de retirada, etiquetas).

Pedidos e reembolsos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado para a MakeCommerce e não pagou, o pagamento foi cancelado, expirou ou falhou, ou a MakeCommerce ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (padrão Processando): o pagamento foi confirmado. Uma nota mostra o valor, a transação, o ambiente e como foi verificado (API da MakeCommerce ou notificação assinada).

Payment On Hold Status (padrão Pendente): o valor ou a moeda pagos eram diferentes do pedido, o valor estava ausente, a transação na MakeCommerce ainda não era final embora informada como concluída, ou o pagamento chegou depois que o pedido foi cancelado. A nota explica. Uma transação com divergência nunca paga o pedido depois; uma transação que não era final completa o pedido quando a MakeCommerce informa que ela foi concluída. Verifique a transação no Merchant Portal e processe o pedido ou reembolse o pagamento.

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

Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse a duplicata no MakeCommerce Merchant Portal. Um pagamento para um pedido reembolsado, ou para um pedido que mudou para outro método de pagamento, apenas acrescenta uma nota.

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

Aba VibeFox MakeCommerce Payment

Em Sales > Orders, abra um pedido pago com a MakeCommerce. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox MakeCommerce Payment mostra todas as transações da MakeCommerce do pedido (data, ID da transação, a etiqueta Test para pagamentos de teste, valor, status e resultado da MakeCommerce), os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos e as MakeCommerce notes do pedido. A aba é exibida para usuários que têm acesso à extensão; os botões dela exigem o direito de modificar a extensão (definido em System > Users > User Groups).

Check MakeCommerce payment status: pede à API da MakeCommerce o status das transações do pedido (a mais recente primeiro), aplica o resultado e adiciona uma nota com o resultado. Use quando um cliente disser que pagou, mas o pedido não tem status.

Reembolsos

Na aba VibeFox MakeCommerce Payment, informe o Amount (o valor ainda não reembolsado já vem preenchido), opcionalmente um Reason (optional), e clique em Refund via MakeCommerce. Confirme a pergunta Refund this amount via MakeCommerce? Reembolsos totais e parciais são aceitos. Os reembolsos são limitados ao valor e à moeda da transação da MakeCommerce; assim, após 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 (teste ou produção), então as chaves desse ambiente precisam estar configuradas. O motivo é enviado à MakeCommerce como comentário do reembolso; sem motivo, o comentário é Refund for order e o número do pedido. Se a MakeCommerce não aceitar o reembolso, a aba mostra o erro, uma nota é adicionada e nenhum reembolso é registrado. Se a MakeCommerce ainda estiver processando o pagamento, a mensagem é MakeCommerce is still processing this payment — try the refund again later. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas com o ID do reembolso da MakeCommerce. Um reembolso total muda o pedido para Refunded Status sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não muda o status. Os reembolsos ficam disponíveis depois que a MakeCommerce confirma o pagamento.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pela MakeCommerce.

Reembolsos feitos no Merchant Portal chegam com o status da transação e são adicionados às notas. O status do pedido não muda automaticamente.

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 MakeCommerce Payment é o primeiro bloco em Extensions > Extensions > Payments > VibeFox MakeCommerce 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 de novo, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-makecommerce 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 administrador (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 único domínio: o endereço da loja definido na configuração 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 MakeCommerce 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 esta prévia não está disponível: a loja não enxerga o login no admin, 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 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 é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A MakeCommerce não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se o ambiente atual tem as suas chaves: Test Shop ID e Test Secret key no modo de teste, Live Shop ID e Live Secret key no modo de produção. Confirme se a moeda do pedido tem no máximo duas casas decimais, 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: as notificações não conseguiram chegar à loja, por exemplo por causa de um firewall ou de autenticação básica. O pedido também recebe o status quando o cliente volta para a loja ou clica em Check again, e quando você clica em Check MakeCommerce payment status na aba do pedido. Confirme se as chaves do ambiente em que o pagamento foi feito estão definidas: a notificação é verificada com a Secret key desse ambiente, e sem ela a MakeCommerce recebe um erro e tenta de novo. Ative o Debug log para ver as notificações.

O pedido está no status de revisão: leia as MakeCommerce notes na aba do pedido (veja Status do pedido), verifique a transação no Merchant Portal e, em seguida, processe o pedido ou reembolse o pagamento.

As notificações são rejeitadas: uma mensagem com assinatura incorreta, de outro pedido, de outra loja ou de uma transação que não foi criada para o pedido é rejeitada, e nada é alterado. Verifique se o Shop ID e a Secret key pertencem à mesma conta e ao mesmo ambiente da MakeCommerce.

O cliente vê um erro depois de Confirm Order: ative o Debug log e veja o campo Log na página da extensão. This payment method is not available. Please reload the checkout page. significa que a sessão do checkout não corresponde mais ao pedido, ou que o método de pagamento foi desativado nesse meio-tempo: o cliente precisa recarregar o checkout. Uma moeda que a MakeCommerce não pode cobrar gera MakeCommerce cannot process payments in seguido do código da moeda.

O reembolso falha com uma mensagem sobre o ambiente: o pedido foi pago no ambiente de teste ou de produção, e as chaves desse ambiente não estão configuradas. Informe-as e tente de novo.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento ainda não está confirmado, já foi totalmente reembolsado, o seu grupo de usuários não tem o direito de modificar a extensão, o pedido foi mudado para outro método de pagamento, ou as chaves do ambiente do pagamento não estão definidas.

Para desenvolvedores: a extensão dispara os eventos do OpenCart wc_mkc_transaction_data, wc_mkc_customer_data, wc_mkc_supported_locales e wc_mkc_is_available para alterar os dados da transação, os dados do cliente, os idiomas da página de pagamento e a disponibilidade do método.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox MakeCommerce 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 (startup action), que deixa passar as notificações no modo de manutenção). Se Delete data estiver ativado, as demais configurações (título, descrição, modo de teste, Shop IDs, Secret keys, log de depuração) e o log são removidos. Se estiver desativado, são mantidos para uma reinstalação posterior. As transações e os reembolsos da MakeCommerce 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.

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

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