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

Conta de comerciante no iPay88: o Merchant Code e a Merchant Key são emitidos pelo iPay88 quando a sua conta de comerciante é ativada. Eles também aparecem no portal de comerciante do iPay88. Se você ainda não é comerciante, faça o cadastro no site do iPay88. Mantenha a Merchant Key em sigilo: ela assina os pagamentos. O iPay88 não tem sandbox separado, por isso não há chaves de teste.

URL de requisição: o endereço do seu site precisa estar cadastrado no iPay88 como URL de requisição. Caso contrário, a página do iPay88 mostra "Permission not allow".

Moeda: Malaysia — MYR, e USD, SGD, AUD, CAD, EUR, GBP, HKD, CNY, TWD, INR, IDR, PHP ou THB se a opção multimoeda estiver ativada na sua conta do iPay88; Philippines — PHP ou USD; Indonesia — IDR; Thailand — THB. Se a moeda do carrinho não puder ser cobrada na sua região, o método de pagamento fica oculto na finalização da compra.

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

Instalação

1. No back office, vá em 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 encontre depois o VibeFox iPay88 Payment na lista de módulos e clique em Configure.

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

4. Escolha a sua iPay88 region, informe o Merchant Code e a Merchant Key, ative Enable/Disable e clique em Save.

5. Para verificar a configuração, faça um pagamento com o Test mode ativado e depois desative o modo de teste.

Ao ser instalado, o módulo cria dois status de pedido: Awaiting iPay88 payment e iPay88 payment on hold. O PrestaShop habilita o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences. Um país que você ativar depois de instalar o módulo também precisa estar marcado para o módulo ali; caso contrário, os clientes desse país não verão o iPay88. As URLs de resposta e de backend são enviadas em cada pagamento.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox iPay88 Payment > Configure. Cada botão Save salva a página inteira. Acima dos campos, a página mostra Informe o Merchant Code e a Merchant Key do iPay88 — até lá, o método de pagamento não é exibido na finalização da compra. enquanto faltar uma chave, um aviso quando a moeda padrão da loja não puder ser cobrada na região selecionada (o método de pagamento fica então oculto na finalização da compra) e um aviso enquanto o modo de teste estiver ativo.

iPay88

Enable/Disable: Enable iPay88 Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que o cliente vê na finalização da compra. Também é o nome do método de pagamento salvo no pedido. Padrão: iPay88.

Description: o texto exibido abaixo do método de pagamento na finalização da compra. Padrão: Pay securely via iPay88 (credit card, online banking, e-wallet).

Conta do iPay88

iPay88 region: o país da sua conta de comerciante no iPay88. Ele define a página de pagamento do iPay88 e as moedas que podem ser cobradas. O pedido é sempre cobrado na própria moeda. Padrão: Malaysia.

Merchant Code: o seu Merchant Code do iPay88, por exemplo M01234.

Merchant Key: a sua Merchant Key do iPay88. Ela assina as solicitações de pagamento e verifica as respostas do iPay88. Mantenha-a em sigilo. A chave salva nunca é exibida novamente: o campo fica vazio e mostra Salva — deixe em branco para mantê-la. Digite um valor novo somente se quiser alterá-la. A chave é salva exatamente como você a digitou, incluindo aspas e barras invertidas.

Clear saved secret: marque Merchant Key e clique em Save para remover a chave salva. Um campo vazio mantém o valor salvo.

Signature type: como as solicitações de pagamento são assinadas. As respostas são verificadas nos dois formatos, então os pagamentos iniciados antes de uma troca continuam verificáveis.

Pagamento

Payment method: pré-selecione um método de pagamento do iPay88 da lista de PaymentId da Malaysia, ou deixe Let the customer choose on the iPay88 page (padrão). A lista inclui Credit Card (MYR), FPX (Online Banking), Maybank2U, Alliance Online, AmBank, RHB Bank, Hong Leong Bank, CIMB Clicks, Web Cash, PayPal (MYR), Credit Card (PHP), Boost, Touch n Go eWallet, GrabPay e ShopeePay.

Reference prefix: opcional. É adicionado antes do número do carrinho na referência do iPay88 (RefNo), por exemplo SHOP1-. Use um prefixo diferente em cada loja que usa a mesma conta do iPay88, para que a resposta de uma loja nunca seja aplicada ao carrinho de outra. Letras, dígitos, "-" e "_", até 10 caracteres. Os demais caracteres são removidos ao salvar, e um prefixo que termina em dígito recebe "-" no final, porque o número do carrinho é lido a partir do fim do RefNo. A página então mostra o valor salvo. Se você migrar do WooCommerce para o PrestaShop com a mesma conta do iPay88, defina um prefixo para que as novas referências nunca repitam números de pedidos antigos.

Test mode: Charge a fixed test amount instead of the order total. O iPay88 não tem sandbox separado: os pagamentos de teste são transações reais na página ao vivo do iPay88, com um valor pequeno (1,00; IDR 10.000). O pedido é marcado como pago quando o valor de teste é recebido, e a nota do pedido informa isso. Enquanto o modo de teste estiver ativo, a finalização da compra exibe TEST MODE: only a test amount of ... will be charged. Um pagamento iniciado no modo de teste é sempre conferido contra o valor de teste, mesmo que você desative o modo de teste antes de o iPay88 responder. Nunca deixe o modo de teste ativo em uma loja em produção. Padrão: desativado.

URLs de resposta e de backend

O módulo envia as duas URLs em cada pagamento, então não há nada a configurar. Se o iPay88 pedir, copie-as desta seção. Com URLs amigáveis, elas ficam assim: https://your-shop/module/wcp_ipay88_payment/response (Response URL, o retorno do cliente) e https://your-shop/module/wcp_ipay88_payment/backend (Backend URL, a notificação de servidor para servidor), possivelmente com um código de idioma como /en/. A seção também mostra o endereço do seu site, que deve estar cadastrado no iPay88 como URL de requisição.

As duas respostas do iPay88 são conferidas da mesma forma: os campos obrigatórios, a assinatura feita com a sua Merchant Key e a referência de um pagamento que esta loja iniciou para este carrinho. Respostas sem assinatura válida são rejeitadas e nunca alteram um carrinho ou um pedido. A notificação de backend recebe RECEIVEOK somente depois de processada; caso contrário, o iPay88 a envia novamente. Ela funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja. O iPay88 informa estes status de pagamento:

Avançado

Debug log: registra as solicitações de pagamento e as respostas do iPay88 em logs/ipay88_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Nenhum dado pessoal, Merchant Key ou assinatura é registrado. Erros e avisos são sempre registrados, mesmo com a chave desativada. Padrão: desativado.

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

Delete data on uninstall: apaga as configurações, os registros e os dados de pagamento do iPay88 quando o módulo é desinstalado. Pedidos e status de pedidos nunca são apagados. Padrão: desativado.

Finalização da compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão iPay88) e confirma. A página seguinte mostra Redirecting to iPay88 payment gateway... e Please do not close this window. enquanto um formulário é enviado à página de pagamento do iPay88 da sua região. Sem JavaScript, o cliente clica em Pay Now. Nesse momento ainda não existe pedido. O módulo envia o total do carrinho na moeda do carrinho (o valor de teste no modo de teste), os nomes dos produtos e o nome, e-mail e telefone do cliente. Na página do iPay88, o cliente paga com cartão, FPX (internet banking), carteira eletrônica ou outro método oferecido pela sua conta.

O pedido só é marcado como pago quando o iPay88 o confirma com uma resposta assinada, seja no retorno do cliente, seja pela notificação de backend. Depois de um pagamento bem-sucedido, o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your iPay88 payment has been received. Para um pagamento pendente, a página mostra Your payment is pending confirmation from iPay88. We will update your order as soon as the payment is confirmed. Para um pedido em espera, mostra We have received a payment notification from iPay88 and are reviewing it. We will contact you if anything is needed. Se o pedido estiver em Payment error ou tiver sido cancelado, mostra The payment was not completed. Please contact us.

Se a confirmação estiver sendo processada ao mesmo tempo pela notificação de backend, o cliente vê We have not received the payment confirmation from iPay88 yet. If you completed the payment, your order will be updated shortly. com os botões Check again e Back to checkout.

Se o pagamento foi recusado ou cancelado, nenhum pedido é criado e o carrinho é mantido. O cliente volta à finalização da compra com The payment was not completed: e o motivo do iPay88, seguido de You can try again or choose another payment method. Cada tentativa com o mesmo carrinho usa o mesmo RefNo. Se a resposta não puder ser verificada, o cliente vê The payment response could not be verified. If you completed the payment, please contact us with your order number — the payment will be checked manually. com um botão Return to the store.

Se o pagamento não puder ser iniciado, o cliente volta à finalização da compra com This payment method is temporarily unavailable. Please choose another payment method. (chaves ausentes ou total zero) ou iPay88 cannot accept payments in ... Please choose another payment method. (moeda não cobrável na região). Se o carrinho já tiver um pedido (pago ou aguardando um pagamento pendente), nenhum segundo formulário de pagamento é gerado e o cliente é enviado à página de confirmação do pedido.

O módulo aceita apenas pagamentos únicos. Não há reembolsos pelo PrestaShop, cartões salvos, assinaturas, pré-autorização e captura, nem campos de cartão no seu site. Ele não consulta o iPay88 novamente sobre o status do pagamento: os pedidos são atualizados somente pela resposta do iPay88 e pela notificação de backend.

Pedidos

Order statuses

No order yet: o cliente foi enviado ao iPay88 e ainda não chegou nenhum resultado, ou o pagamento foi recusado. Existe apenas o carrinho.

Payment accepted: o iPay88 informou um pagamento bem-sucedido com o valor e a moeda esperados. O pagamento é registrado com o TransId do iPay88 como ID da transação. Uma nota privada mostra o TransID, o PaymentID, o valor e a moeda. No modo de teste, uma segunda nota informa que o valor de teste foi cobrado no lugar do total do pedido.

Awaiting iPay88 payment: o iPay88 informou o pagamento como pendente. O pedido passa para Payment accepted quando o iPay88 o confirma, ou para Payment error se ele falhar.

Payment error: um pagamento pendente falhou depois. A nota mostra o motivo informado pelo iPay88. Este carrinho já tem um pedido, então o cliente não pode pagá-lo de novo e faz um novo pedido.

iPay88 payment on hold: o iPay88 informou um pagamento bem-sucedido com valor ou moeda diferentes do pedido, ou o pagamento chegou depois que o pedido foi cancelado. O pedido NÃO foi marcado como pago. A nota explica isso. Confira o pagamento no portal do iPay88 e, depois, processe o pedido ou reembolse o pagamento.

Um pedido pago ou reembolsado nunca é alterado por uma resposta posterior. Se chegar outro pagamento bem-sucedido para ele, uma nota pede que você o confira no portal do iPay88 e o reembolse se for duplicado. Uma resposta de falha nunca altera um pedido pago, reembolsado ou cancelado. Respostas repetidas não acrescentam nada.

Bloco de pagamento do iPay88

A página do pedido mostra um bloco iPay88 payment com o RefNo, TransId, status, valor solicitado, valor recebido, PaymentId, AuthCode, erro e região, além de um selo TEST MODE para os pagamentos de teste.

Reembolsos

Os reembolsos não são enviados ao iPay88 a partir do PrestaShop. Reembolse o pagamento no portal de comerciante do iPay88 e, em seguida, registre o reembolso manualmente no PrestaShop.

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 iPay88 Payment é o primeiro bloco de Modules > Module Manager > VibeFox iPay88 Payment > 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 estão a linha Product: presta-payment-ipay88 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 muda, ou depois que você libera uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser contatado, 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 na sua conta vibefox.net.

Sem uma chave ativa, o iPay88 não é exibido aos clientes na finalização da compra. 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 na finalização da compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 informada 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

O iPay88 não aparece na finalização da compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o Merchant Code e a Merchant Key foram informados e se a moeda do carrinho pode ser cobrada na iPay88 region selecionada. A página de configurações mostra um aviso quando algo está faltando. 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 aprovado, mas nenhum pedido foi criado: nem o retorno do cliente nem a notificação de backend chegaram à sua loja com uma assinatura válida. Veja o campo Log: os erros são sempre registrados. Confira se a Merchant Key é exatamente a que o iPay88 forneceu e se o seu servidor aceita solicitações do iPay88 na Backend URL exibida nas configurações.

A página do iPay88 mostra "Permission not allow": o endereço do seu site não está cadastrado no iPay88 como URL de requisição. Peça ao iPay88 que cadastre o endereço mostrado na seção Response and backend URLs.

A notificação de backend responde BAD SIGNATURE: a assinatura não corresponde à Merchant Key. Confira a Merchant Key. Nada foi alterado.

A notificação de backend responde NOT CONFIGURED: o Merchant Code ou a Merchant Key não estão definidos, então a resposta não pode ser verificada. O iPay88 envia a notificação novamente.

A notificação de backend responde UNKNOWN ORDER: nenhum pagamento do iPay88 foi iniciado para esta referência nesta loja, por exemplo porque outra loja com a mesma conta não usa Reference prefix ou usa o mesmo prefixo, ou porque os dados de pagamento do iPay88 foram apagados na desinstalação.

A notificação de backend responde RETRY: o carrinho estava sendo confirmado pelo retorno do cliente no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). O iPay88 envia a notificação novamente.

A Backend URL mostra BAD REQUEST no navegador: isso é normal. A URL aceita apenas solicitações assinadas pelo iPay88.

O pedido está em iPay88 payment on hold: o iPay88 informou um pagamento que não corresponde ao pedido, ou o pedido tinha sido cancelado. Confira a nota do pedido e o pagamento no portal do iPay88, depois conclua o pedido ou reembolse o pagamento.

O cliente vê "iPay88 cannot accept payments in" seguido de uma moeda: a moeda do carrinho não pode ser cobrada na região selecionada. No iPay88 Malaysia, moedas diferentes de MYR também exigem a opção multimoeda na sua conta do iPay88.

Clientes reais são cobrados apenas 1,00: o Test mode está ativo. Desative-o.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox iPay88 Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. A confirmação informa que as configurações e os dados de pagamento do iPay88 são mantidos, a menos que Delete data on uninstall esteja ativado. Se estiver ativado, as configurações, os registros e os dados de pagamento do iPay88 são removidos. Se estiver desativado, tudo é mantido para uma reinstalação posterior. Os status de pedido Awaiting iPay88 payment e iPay88 payment on hold são sempre mantidos. Os pedidos nunca são apagados e mantêm suas notas de pagamento e IDs de transação.

iPay88 é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pelo iPay88.