VibeFox Moyasar for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Moeda: a moeda do carrinho deve ser SAR, AED, USD, EUR, KWD, BHD ou OMR. Para qualquer outra moeda, o método de pagamento fica oculto no checkout.

Conta Moyasar: você precisa das chaves secretas de API da sua conta Moyasar (teste e produção). Apenas as chaves secretas são usadas. A chave publicável não é necessária, porque o pagamento acontece na página da Moyasar. É recomendável um webhook no Moyasar Dashboard (veja Configuração).

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um 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 envio terminar, clique em Configure ou, depois, encontre VibeFox Moyasar Payment Gateway na lista de módulos e clique em Configure.

3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. Cole as suas chaves secretas da Moyasar e clique em Save. Configure o webhook no Moyasar Dashboard (veja Configuração).

5. Ative Enable/Disable e clique em Save. Faça um pedido de teste no modo de teste e depois desative Test mode.

Na instalação, o módulo cria dois status de pedido: Awaiting Moyasar payment e Moyasar payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando o modo atual não tem chave secreta (nesse caso, o método de pagamento fica oculto no checkout), quando nenhum segredo compartilhado do webhook está salvo (nesse caso, o webhook rejeita todas as chamadas) ou quando a moeda padrão da loja não é suportada. Enquanto o módulo estiver ativado no modo de teste, ele exibe Test mode is active: payments are simulated, no money is charged. Ao salvar, o módulo recusa uma chave publicável, uma chave do outro modo ou uma chave com espaços, mantém o valor anterior e mostra o motivo.

Moyasar

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

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. Padrão: Pay with Moyasar. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. No modo de teste, o checkout acrescenta (Test mode: no real payment is made.)

Chaves de API

Copie as chaves secretas em Moyasar Dashboard > Settings > API Keys. As chaves de teste e de produção são separadas. O modo de teste usa somente a chave de teste; o modo de produção, somente a chave de produção.

Test mode: usa a chave secreta de teste: os pagamentos são simulados e nenhum valor é cobrado. Padrão: ligado. Desligue para aceitar pagamentos reais com a chave secreta de produção.

Test secret key: a chave secreta do modo de teste. Começa com sk_test_.

Live secret key: a chave secreta do modo de produção. Começa com sk_live_.

Chaves e segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Notificações de pagamento (webhook)

O webhook é recomendado, mas não obrigatório. Os pedidos também são confirmados quando o cliente volta para a loja e pela notificação da fatura que a Moyasar envia automaticamente à sua loja quando a fatura é paga. O webhook cobre clientes que fecham o navegador antes de voltar e informa os reembolsos feitos no Moyasar Dashboard. Adicione-o em Moyasar Dashboard > Settings > Webhooks.

Webhook URL: exibida somente para leitura, com um botão Copy. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. Método HTTP: POST.

Webhook shared secret: insira o mesmo valor de Shared secret do webhook na Moyasar. Se nada estiver salvo, Save gera um segredo aleatório; Generate a new secret substitui o salvo. Um segredo gerado é exibido uma única vez acima das configurações, após salvar, e nunca mais; por isso copie-o para a Moyasar imediatamente. Webhooks sem o segredo compartilhado correto são rejeitados.

Selecione estes eventos para o webhook (eles também estão listados nesta seção):

Nenhum dado de um webhook ou notificação é aceito diretamente: para cada um, o módulo lê a fatura na API da Moyasar com a chave secreta do modo em que a fatura foi criada e verifica se ela foi criada para este carrinho. Pagamentos de outras integrações na mesma conta Moyasar são ignorados. Um único segredo compartilhado serve para os dois modos.

Pedidos

Status after payment: o status do pedido definido após um pagamento confirmado. O pedido é criado diretamente nesse status.

Avançado

Clear saved secrets: marque Test secret key, Live secret key ou Webhook shared secret e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Debug log: registra chamadas à API e notificações em logs/moyasar_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves de API, dados de cartão e dados de clientes nunca são registrados. Padrão: desligado.

Log: mostra o tamanho atual e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.

Clean uninstall: quando ligado, desinstalar o módulo apaga as configurações do módulo e o registro. Os dados de pagamento salvos com os pedidos (IDs da fatura e do pagamento na Moyasar) são mantidos, para que os reembolsos continuem rastreáveis. Padrão: desligado.

Checkout

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Pay with Moyasar) e confirma. O módulo cria uma fatura da Moyasar para o total do carrinho na moeda do carrinho e envia o cliente para a página de pagamento dela. Lá, o cliente paga com qualquer método ativo na sua conta Moyasar. A fatura mostra Order #, o número do carrinho e o nome da sua loja. Nesse momento, ainda não existe pedido.

O pedido só é marcado como pago depois que a Moyasar confirma: o módulo lê a fatura na API da Moyasar e verifica se ela está paga, se pertence a este carrinho e se tem exatamente o valor e a moeda do carrinho. Só então o pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Your payment with Moyasar has been received. Se a Moyasar retiver o pagamento para análise, a página mostra Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Se o pedido estiver em espera para a sua análise, a página informa que o pagamento foi recebido e que o pedido está sendo analisado. Se um pagamento em análise falhar depois, ou se o pedido não pago for cancelado, a página mostra Your Moyasar payment was not completed. Please contact us about this order.

Se o cliente voltar sem pagar (por exemplo, com o botão voltar da página de pagamento), ele retorna ao checkout com uma destas mensagens: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. ou, quando o pagamento ainda não puder ser verificado, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. O carrinho é mantido.

O cliente pode tentar novamente. Se a página de pagamento aberta do carrinho ainda tiver o mesmo valor e a mesma moeda, ela é reutilizada. Se o total do carrinho tiver mudado, a página de pagamento antiga é cancelada na Moyasar e uma nova é criada, de modo que a antiga não pode mais ser paga. Se a fatura anterior já estiver paga, o pedido é criado em vez de um novo pagamento.

Se a Moyasar não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta, por exemplo The Moyasar payment service is not responding. Please try again in a few minutes., e pode escolher outro método de pagamento. Os detalhes são gravados no registro.

O webhook e a notificação da fatura funcionam com a loja em modo de manutenção e não são bloqueados pela restrição de países da sua loja.

O módulo aceita apenas pagamentos únicos na página da Moyasar. Não há formulário de cartão no seu próprio checkout, nem cartões salvos ou tokenização, nem assinaturas, nem autorização e captura separadas.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado à Moyasar e não pagou, ou a Moyasar ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted, Delivered ou Moyasar payment on hold: o pagamento foi confirmado. O status segue Status after payment. O pagamento é registrado com o ID de pagamento da Moyasar como ID da transação, e uma nota mostra como o pagamento foi confirmado (webhook, notificação da fatura, retorno do cliente ou checkout), o ID da fatura, o ID do pagamento e o método de pagamento.

Awaiting Moyasar payment: a Moyasar retém o pagamento para análise. O pedido passa para o status pago quando a Moyasar confirma o pagamento.

Erro de pagamento: o pagamento que estava em análise falhou.

Moyasar payment on hold after payment: a Moyasar informou um valor ou uma moeda diferente do total do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou), ou a fatura foi paga depois que você cancelou o pedido. O pedido não é marcado como pago, mas o valor efetivamente recebido é registrado quando está na moeda do pedido. A nota explica isso. Verifique o pagamento no Moyasar Dashboard e atenda o pedido ou reembolse o pagamento.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Um pedido pago nunca é revertido por eventos posteriores. Se uma segunda fatura de um carrinho já pago também for paga (por exemplo, a partir de duas abas do navegador), o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no Moyasar Dashboard.

Bloco de pagamento da Moyasar

A página do pedido mostra um bloco Moyasar payment com o ID da fatura da Moyasar, o ID do pagamento, o método (por exemplo, a bandeira do cartão e os últimos quatro dígitos), o status, os valores pagos e reembolsados, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Moyasar notes do pedido.

Reembolsos

No bloco Moyasar payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Moyasar. Confirme a pergunta Refund this amount through Moyasar? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa da permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos no valor e na moeda cobrados pela Moyasar, então, 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 total de um pagamento com cartão feito há menos de 2 horas é enviado como anulação (void): cancelamento antes da liquidação, sem taxas. Caso contrário, é um reembolso. O reembolso usa a chave secreta do modo em que o pagamento foi feito (teste ou produção), então essa chave precisa estar configurada. O módulo verifica primeiro na Moyasar a moeda, o status e o valor reembolsável do pagamento. Se a Moyasar não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso ou anulação bem-sucedido é adicionado ao histórico de reembolsos e às notas. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que a Moyasar confirma o pagamento.

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

Reembolsos e anulações feitos no Moyasar Dashboard chegam pelo webhook. Se a Moyasar mostrar mais valor reembolsado do que o módulo registrou, uma nota é adicionada ao pedido. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente, se necessário, sem usar Refund via Moyasar.

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 Moyasar Payment Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-moyasar e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o 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 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 vibefox.net.

Sem uma chave ativa, a Moyasar não é exibida aos clientes no checkout. Se mesmo assim um pagamento for iniciado, 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 a forma de pagamento também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A Moyasar não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ligado, se o modo atual tem uma chave secreta (Test secret key no modo de teste, Live secret key no modo de produção) e se a moeda do carrinho é SAR, AED, USD, EUR, KWD, BHD ou OMR. A página de configurações mostra um aviso quando a chave está ausente ou a moeda da loja não é suportada. 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.

O pagamento foi feito, mas nenhum pedido foi criado: as confirmações não chegaram à sua loja. Configure o webhook: no Moyasar Dashboard, verifique se ele existe, se a URL é exatamente a Webhook URL das configurações, se o método é POST, se os quatro eventos estão selecionados e se o segredo compartilhado é igual ao salvo em Webhook shared secret. O pedido também é criado quando o cliente volta para a loja ou tenta pagar novamente o mesmo carrinho.

O webhook responde Unauthorized: o segredo compartilhado na Moyasar é diferente do salvo. Digite o segredo do webhook da Moyasar em Webhook shared secret e salve, ou marque Generate a new secret, salve e cole na Moyasar o segredo exibido.

O webhook responde Webhook secret not configured: nenhum segredo compartilhado está salvo, por exemplo depois de removê-lo com Clear saved secrets. Clique em Save para gerar um e copie-o para a Moyasar.

O webhook responde Key not configured: a fatura foi criada em um modo (teste ou produção) cuja chave secreta está vazia. Insira essa chave.

O webhook responde Verification failed ou Try again later: não foi possível ler a fatura na API da Moyasar, o carrinho estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Moyasar tenta o webhook novamente. Ligue o Debug log para ver o motivo.

A URL do webhook mostra Method not allowed no navegador: é normal. A URL aceita apenas requisições POST da Moyasar.

Erro ao salvar sobre a chave: foi colada uma chave publicável (pk_...) ou uma chave do outro modo, ou a chave contém espaços. O valor anterior foi mantido. Chaves de teste começam com sk_test_, chaves de produção com sk_live_.

O cliente vê um erro ao escolher a Moyasar: ligue o Debug log e veja o campo Log na página do módulo. This payment method is temporarily unavailable. Please choose another payment method or contact us. normalmente indica uma chave secreta errada ou ausente. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. significa que o carrinho já tem uma fatura paga que não pôde ser transformada em pedido; verifique o registro.

Order is Moyasar payment on hold after payment: leia as Moyasar notes no bloco Moyasar payment. O valor ou a moeda pagos eram diferentes do carrinho, ou o pagamento chegou depois que o pedido foi cancelado. Atenda o pedido ou reembolse o pagamento.

Falha no reembolso: leia a mensagem. Se o pagamento foi feito no outro modo, informe a chave secreta desse modo. Se o valor for maior que o ainda reembolsável na Moyasar, parte do pagamento já foi reembolsada, por exemplo no Moyasar Dashboard. Se a Moyasar não confirmou o valor reembolsado, verifique o pagamento no Moyasar Dashboard antes de tentar novamente.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Moyasar Payment Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Clean uninstall estiver ligado, as configurações do módulo e o registro são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. As faturas, pagamentos e reembolsos da Moyasar e os status de pedido Awaiting Moyasar payment e Moyasar payment on hold são sempre mantidos, para que pedidos antigos possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.

A Moyasar é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Moyasar nem endossado por ela.