VibeFox Moyasar for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. Com uma versão mais antiga do WooCommerce, o plugin mostra um aviso e não é carregado.

PHP: 8.0 ou superior.

Moeda: a moeda da loja ou do pedido 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 de API secretas da sua conta Moyasar (de teste e de produção). Somente as chaves secretas são usadas. A chave publicável não é necessária, porque o pagamento acontece na página da Moyasar. Um webhook no Moyasar Dashboard é recomendado (veja Configuração).

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

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_moyasar_payment_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Moyasar > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Cole suas chaves secretas da Moyasar e salve. Configure o webhook no Moyasar Dashboard com a URL e o segredo compartilhado exibidos nas configurações (veja Configuração).

6. Ative Enable/Disable. Faça um pedido de teste com o modo de teste ativo e depois desmarque Test mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Moyasar. O título da página mostra um selo TEST MODE ou LIVE. 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) ou quando a moeda da loja não é suportada, e mostra Test mode is active: payments are simulated, no money is charged. enquanto o modo de teste estiver ativo. Na lista de métodos de pagamento, a Moyasar aparece como pendente de configuração até que o modo atual tenha uma chave secreta. Ao salvar, o plugin 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. Ele também avisa quando o gateway está ativado, mas a chave secreta do modo atual está vazia.

Geral

Enable/Disable: Enable Moyasar 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. Padrão: Pay with Moyasar.

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 apenas a chave de teste, e o modo de produção usa apenas a chave de produção.

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

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

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

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 de fatura que a Moyasar envia automaticamente para a sua loja quando a fatura é paga. O webhook cobre clientes que fecham o navegador antes de voltar e informa sobre reembolsos feitos no Moyasar Dashboard. Em Moyasar Dashboard > Settings > Webhooks, adicione um webhook com a URL e o segredo compartilhado desta seção, método HTTP POST.

Webhook URL: exibida somente leitura, com um botão Copy. Tem este formato: https://your-site/wp-json/moyasar_p/v1/webhook. Método HTTP: POST.

Webhook shared secret: informe o mesmo valor de Shared secret do webhook na Moyasar. Deixe o campo vazio e salve para gerar um segredo aleatório; depois clique em Show e copie-o para a Moyasar. Webhooks sem o segredo compartilhado correto são rejeitados.

Selecione estes eventos para o webhook:

Nenhum webhook ou notificação é considerado confiável diretamente: para cada um, o plugin lê a fatura na API da Moyasar com a chave secreta do modo do pedido e verifica se ela foi criada para esse pedido. Pagamentos de outras integrações na mesma conta Moyasar são ignorados.

Pedidos

Status after payment: o status do pedido definido após um pagamento confirmado. O status é definido de imediato, sem uma segunda mudança de status.

Avançado

Debug log: Log API calls and notifications grava os detalhes em WooCommerce > Status > Logs, origem wcp_moyasar_payment_gateway. Os erros são sempre registrados. Chaves de API, dados de cartão e dados de clientes nunca são registrados. Padrão: desativado.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Os dados de pagamento armazenados nos pedidos (IDs da fatura e do pagamento na Moyasar) são mantidos, para que os reembolsos continuem rastreáveis. Padrão: desativado.

Checkout

O cliente escolhe o método de pagamento (por padrão, Pay with Moyasar) e faz o pedido. O plugin cria uma fatura da Moyasar para o total do pedido na moeda do pedido e envia o cliente para a página de pagamento. Lá, o cliente paga com qualquer método ativo na sua conta Moyasar, por exemplo mada, Visa, Mastercard, Apple Pay ou STC Pay. A fatura mostra Order, o número do pedido e o nome do seu site.

O pedido só é marcado como pago depois que a Moyasar confirma: o plugin lê a fatura na API da Moyasar e verifica se ela está paga, pertence a este pedido e tem exatamente o valor e a moeda do pedido. Depois de pagar, o cliente volta para a página de pedido recebido da sua loja. Se o cliente voltar sem pagar (por exemplo, pelo botão voltar da página de pagamento), ele retorna ao checkout ou à página Pay for order 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 pode 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.

Um cliente pode pagar novamente um pedido não pago. Se a página de pagamento ainda aberta do pedido tiver o mesmo valor e a mesma moeda, ela é reutilizada. Se o total do pedido mudou, a página de pagamento antiga é cancelada e uma nova é criada, de modo que a antiga não pode mais ser paga. Se a fatura anterior já estiver paga, o pedido é confirmado em vez de criar um novo pagamento.

Se a Moyasar não conseguir iniciar o pagamento, o cliente vê 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 log.

O método de pagamento funciona no checkout clássico, no bloco Checkout e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

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

Pedidos e reembolsos

Status do pedido

Pending payment: a fatura foi criada e o cliente ainda não pagou. A nota do pedido mostra o ID da fatura, o valor e o modo.

Processing, Completed or On hold: o pagamento foi confirmado. O status segue Status after payment. A nota do pedido 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. O ID da transação é o ID do pagamento na Moyasar.

On hold after payment: a Moyasar informou um valor ou uma moeda diferente do total do pedido (o pedido não é marcado como pago), ou a fatura foi paga depois que o pedido foi cancelado. A nota do pedido explica o caso. Verifique o pagamento no Moyasar Dashboard e então atenda o pedido ou reembolse o pagamento.

On hold before payment: a Moyasar retém o pagamento para análise. O pedido é atualizado quando a Moyasar decidir.

Failed: a última fatura de um pedido não pago foi recusada, expirou ou foi cancelada. O cliente pode tentar pagar novamente.

Cancelled: o pedido foi cancelado pelo cliente, por você ou pelo tempo limite de reserva de estoque do WooCommerce. A fatura aberta da Moyasar do pedido também é cancelada, para que não possa mais ser paga.

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

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Pay with Moyasar (o botão usa o título do método de pagamento). Reembolsos totais e parciais são aceitos para pedidos com pagamento pela Moyasar. O reembolso total de um pagamento com cartão feito há menos de 2 horas é enviado como anulação (cancelamento antes da liquidação); caso contrário, é um reembolso. O reembolso usa a chave secreta do modo em que o pagamento foi feito (teste ou produção), por isso essa chave precisa estar configurada. Antes de reembolsar, o plugin verifica o pagamento na Moyasar: moeda, status e o valor que ainda pode ser reembolsado. Se a Moyasar não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso ou uma anulação bem-sucedidos são adicionados às notas do pedido.

Os reembolsos e anulações feitos no Moyasar Dashboard chegam pelo webhook. Se a Moyasar mostrar mais valor reembolsado do que o WooCommerce, uma nota é adicionada ao pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Pay with Moyasar.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Moyasar. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.

Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta da vibefox.net.

Sem uma chave ativa, a Moyasar 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. Os gerentes da loja conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

A Moyasar não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado, 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 da loja ou do pedido é 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 não é suportada.

O pagamento foi feito, mas o pedido continua em Pending payment: as confirmações não chegaram à sua loja. Configure o webhook: no Moyasar Dashboard, verifique se ele existe, se sua 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 Webhook shared secret. O pedido também é confirmado quando o cliente volta para a loja e quando tenta pagar o mesmo pedido novamente.

O webhook responde Unauthorized: o segredo compartilhado na Moyasar é diferente do Webhook shared secret. Clique em Show, copie o valor e cole no webhook da Moyasar.

O webhook responde Webhook secret not configured: as configurações ainda não foram salvas com um segredo compartilhado. Salve as configurações para gerar um e copie-o para a Moyasar.

O webhook responde Key not configured: o pedido foi pago em um modo (teste ou produção) cuja chave secreta está vazia. Informe essa chave.

O webhook responde Verification failed ou Try again later: não foi possível ler a fatura na API da Moyasar, ou o pedido estava sendo atualizado por outra solicitação no mesmo momento. A Moyasar tenta o webhook novamente.

Erro ao salvar sobre a chave: foi colada uma chave publicável (pk_...) ou uma chave do outro modo. 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 fazer o pedido: ative Debug log e consulte WooCommerce > Status > Logs, origem wcp_moyasar_payment_gateway. This payment method is temporarily unavailable. Please choose another payment method or contact us. normalmente indica uma chave secreta incorreta 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 pedido já tem uma fatura paga que precisa da sua análise.

O pedido está em On hold after payment: leia a nota do pedido. O valor ou a moeda pagos eram diferentes do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Atenda o pedido ou reembolse o pagamento.

O reembolso falha: leia a mensagem. Se o pagamento foi feito no outro modo, informe a chave secreta desse modo. Se o valor for maior do que o que ainda pode ser reembolsado 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.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta da vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway e os logs só são removidos se Clean uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Moyasar é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado à Moyasar nem endossado por ela.