VibeFox MultiSafepay 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 uma que a MultiSafepay aceite, por exemplo EUR, USD, GBP, PLN, CHF, SEK, DKK ou NOK. Para outras moedas, o método de pagamento não é exibido no checkout.

Conta na MultiSafepay: você precisa da chave de API do seu site no MultiSafepay Control. As contas de teste e de produção têm chaves diferentes. Não é preciso configurar mais nada na MultiSafepay: o endereço de notificação é enviado com cada pagamento.

Site público: a MultiSafepay precisa conseguir acessar a sua loja para enviar notificações. Caso contrário, os pedidos ainda são criados quando o cliente volta da MultiSafepay.

Chave de licença VibeFox: comprada 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, mais tarde, encontre o VibeFox MultiSafepay 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 a chave de API de teste e/ou de produção do MultiSafepay Control (veja Configuração).

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

Na instalação, o módulo cria o status de pedido MultiSafepay 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 estão na página do módulo: Modules > Module Manager > VibeFox MultiSafepay 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 mostra Test mode: new payments use the MultiSafepay test environment (no real payments). enquanto o modo de teste estiver ativado, avisa quando o modo atual não tem chave de API (nesse caso o método de pagamento não é exibido no checkout) e quando a MultiSafepay não aceita a moeda padrão da sua loja. A página não salva sem um Title.

Checkout

Enable/Disable: Enable MultiSafepay 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. Também é o nome do método de pagamento salvo no pedido. Padrão: MultiSafepay. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

Chaves de API

A chave de API fica em MultiSafepay Control > Manage settings > Website settings. A seção traz links para a conta de teste (testmerchant.multisafepay.com) e para a conta de produção (merchant.multisafepay.com). Elas têm chaves diferentes. O modo de teste usa somente a chave de teste, e o modo de produção usa somente a chave de produção.

Test mode: Use the MultiSafepay test environment (no real payments). Ele alterna tanto o endereço da API quanto a chave de API. Pagamentos já feitos continuam usando o ambiente em que foram feitos para verificações de status e reembolsos. Padrão: ativado. Enquanto estiver ativado, os clientes veem Test mode: no real payment will be made. abaixo do método de pagamento.

Test API key: a chave de API da sua conta de teste da MultiSafepay.

Live API key: a chave de API da sua conta de produção da MultiSafepay.

As chaves salvas nunca são mostradas novamente. O campo fica vazio e exibe Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.

Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Notificações

Nada a configurar. O campo Notification URL mostra o endereço enviado à MultiSafepay com cada pagamento. Com URLs amigáveis, ele fica assim: https://your-shop/module/wcp_multisafepay_gateway/webhook, possivelmente com um código de idioma como /en/. Uma notificação apenas informa ao módulo qual pagamento mudou: o status, o valor e a moeda são sempre lidos da API da MultiSafepay com a sua chave de API antes de um pedido ser criado ou alterado. Notificações de pagamentos não iniciados na sua loja são ignoradas. A notificação funciona com a loja em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

Pedidos

Order status after payment: o status de um pedido pago. O status é definido de uma só vez, com uma única mudança de status e um único e-mail ao cliente.

Avançado

Debug log: Log API calls and notifications grava em logs/mspg_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 e dados de clientes nunca são registrados. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e o log. Os dados de pagamento da MultiSafepay dos pedidos e o status do pedido sempre permanecem, para que reembolsos de pedidos antigos continuem possíveis. Desativar o módulo nunca apaga nada. Padrão: desativado.

Checkout

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão MultiSafepay, com o logotipo da MultiSafepay) e confirma. O módulo cria um pagamento da MultiSafepay pelo total do carrinho na moeda do carrinho e envia o cliente à página de pagamento da MultiSafepay. Lá, o cliente escolhe qualquer método de pagamento ativado na sua conta MultiSafepay e paga. O endereço de cobrança, o e-mail, o telefone e o idioma do cliente são passados à MultiSafepay, e o pagamento aparece como Order #, o número do carrinho e o nome da sua loja. Nesse ponto ainda não existe pedido.

Após pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a MultiSafepay confirma: pela notificação ou por uma verificação na API da MultiSafepay quando o cliente retorna. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with MultiSafepay has been received. Para um pedido em espera, a página mostra We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. Se o pagamento falhar depois, a página mostra Your MultiSafepay payment was not completed. Please contact us about this order. Se a MultiSafepay ainda não tiver confirmado o pagamento quando o cliente voltar (por exemplo, quando um depósito bancário está sendo aguardado), a página Payment confirmation mostra o mesmo texto de confirmação e um botão Check again; a notificação cria o pedido assim que a MultiSafepay informar o pagamento.

Se o cliente cancelar na página da MultiSafepay, ou o pagamento for recusado ou expirar, o cliente volta ao checkout com o carrinho mantido e com uma destas mensagens: The MultiSafepay payment was cancelled. You can try again or choose another payment method., The payment was declined. Please try again or choose another payment method. ou The payment session has expired. Please try again.

Antes de criar um novo pagamento para o mesmo carrinho, o módulo verifica o anterior na MultiSafepay. Se ele já estiver pago ou em processamento, o pedido é criado em vez de um novo pagamento. Se ainda estiver aberto com o mesmo valor, a mesma página de pagamento é reutilizada. Se o valor tiver mudado, o pagamento antigo é cancelado na MultiSafepay para que não possa mais ser pago.

Se a MultiSafepay não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta, por exemplo Could not connect to MultiSafepay. Please try again in a moment. ou MultiSafepay cannot accept this order amount or currency. Please choose another payment method. O motivo técnico é registrado no log.

O módulo oferece um único método de pagamento que leva à página da MultiSafepay. Não há métodos de pagamento separados do PrestaShop para cada método de pagamento da MultiSafepay, nem campos de cartão incorporados, nem botões expressos Apple Pay ou Google Pay, nem assinaturas, pagamentos recorrentes ou cartões salvos, e não é possível capturar ou anular pelo PrestaShop. Nenhum dado do carrinho é enviado, então métodos de pagamento pós-pagos que o exigem (por exemplo, Klarna, in3 ou Riverty) não são oferecidos pela MultiSafepay para estes pedidos.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado à MultiSafepay e não pagou, ou a MultiSafepay ainda não confirmou o pagamento. Só existe o carrinho.

Payment accepted ou Delivered: a MultiSafepay confirmou o pagamento (concluído ou enviado). O status segue Order status after payment. O pagamento é registrado com o ID do pedido da MultiSafepay como ID da transação, e uma nota mostra o pagamento, o método de pagamento e o ambiente.

MultiSafepay payment on hold before payment: o pagamento está não liquidado (em análise pela MultiSafepay) ou reservado (autorizado). Capture um pagamento reservado no MultiSafepay Control para receber o dinheiro. O pedido passa automaticamente para o status pago quando a MultiSafepay informa que o pagamento foi concluído.

MultiSafepay payment on hold after payment: a MultiSafepay confirmou um valor ou uma moeda diferentes do total do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), um pagamento de teste foi concluído enquanto o módulo estava no modo de produção (nenhum dinheiro real foi recebido, nenhum pagamento foi registrado), ou o pagamento foi concluído depois que o pedido havia sido cancelado. A nota explica o motivo. Verifique a transação no MultiSafepay Control e depois atenda ou reembolse o pedido.

MultiSafepay payment on hold after a chargeback: a MultiSafepay informou uma contestação de um pedido pago: o dinheiro foi retirado da sua conta.

Payment error: um pagamento não liquidado ou reservado foi depois recusado, cancelado, expirado ou anulado.

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

Um pedido pago ou reembolsado nunca é reaberto por uma notificação atrasada. Se um segundo pagamento for concluído para um carrinho que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o duplicado no MultiSafepay Control.

Bloco de pagamento da MultiSafepay

A página do pedido mostra um bloco MultiSafepay payment com o ID do pedido na MultiSafepay, o método de pagamento, o status, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as MultiSafepay notes do pedido.

Reembolsos

No bloco MultiSafepay payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via MultiSafepay. Confirme a pergunta Refund this amount through MultiSafepay? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa do direito de editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos no valor e na moeda que a MultiSafepay cobrou, então, 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 ao ambiente em que o pagamento foi feito (teste ou produção), por isso a chave de API desse ambiente deve estar definida. Se a MultiSafepay não aceitar o reembolso, o bloco mostra MultiSafepay refund failed: com o erro da MultiSafepay, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso da MultiSafepay. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que a MultiSafepay informa 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 MultiSafepay.

Reembolsos feitos no MultiSafepay Control são adicionados às notas quando a MultiSafepay os informa. O status do pedido e as notas de crédito não são alterados automaticamente. Atualize-os manualmente, se necessário.

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 MultiSafepay Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure, acima das configurações. Insira a chave no campo 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 estão a linha Product: presta-payment-multisafepay 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 único 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 MultiSafepay 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então o método de pagamento também fica oculto para você: você pode 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 novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

A MultiSafepay não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado, se o modo atual tem uma chave de API (Test API key no modo de teste, Live API key no modo de produção) e se a moeda do carrinho é aceita pela MultiSafepay. A página de configurações mostra um aviso quando a chave está ausente ou quando a moeda da loja não é aceita. 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: a notificação não chegou à sua loja. Verifique se a loja está acessível pela internet e se a chave de API do ambiente do pagamento está definida, porque o módulo lê o status pela API da MultiSafepay. Se a API não puder ser acessada ou a chave estiver ausente, a notificação responde ERROR e a MultiSafepay tenta de novo. O pedido também é criado quando o cliente volta à loja e quando tenta pagar o mesmo carrinho novamente.

A notificação responde Invalid request: a requisição não tinha um ID de transação válido. As notificações da MultiSafepay sempre trazem um.

O cliente vê um erro ao escolher a MultiSafepay: ative 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. normalmente indica uma chave de API errada ou ausente. MultiSafepay cannot accept this order amount or currency. Please choose another payment method. significa que a MultiSafepay recusou o valor ou a moeda.

O pedido está em MultiSafepay payment on hold: leia as notas no bloco MultiSafepay payment. O pagamento pode estar não liquidado ou reservado, o valor ou a moeda pagos podem ser diferentes do carrinho, um pagamento de teste pode ter chegado no modo de produção, o pagamento pode ter chegado depois do cancelamento do pedido, ou pode ter havido uma contestação. Verifique a transação no MultiSafepay Control.

Pagamentos de teste não confirmam um pedido real: um pagamento de teste nunca paga um pedido enquanto o módulo estiver no modo de produção; o pedido é colocado em espera. Pagamentos de teste anteriores continuam sendo verificados e reembolsados com a chave de teste depois que você passa para o modo de produção.

O reembolso falha com uma mensagem sobre o ambiente: o pagamento foi feito no ambiente de teste ou de produção, e a chave de API desse ambiente não está definida. Insira-a e tente novamente.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox MultiSafepay Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da MultiSafepay dos pedidos e o status do pedido MultiSafepay payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

MultiSafepay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela MultiSafepay.