VibeFox Klarna for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.

Conta de comerciante no Klarna: você precisa das credenciais de API (nome de usuário e senha) da sua conta de comerciante para uma região de API, e das credenciais de teste do portal do ambiente de testes do Klarna (veja Configuração). Cada região de API tem as suas próprias credenciais. Só é possível usar uma conta de comerciante (uma região de API) por loja.

Moeda: uma moeda do Klarna da sua região: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF ou RON na Europa; USD, CAD ou MXN na América do Norte; AUD ou NZD na Oceania.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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, depois, encontre VibeFox Klarna Payments na lista de módulos e clique em Configure.

3. Informe 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 API region da sua conta de comerciante no Klarna.

5. Informe o nome de usuário e a senha de teste do portal do ambiente de testes do Klarna, mantenha Test mode ativado, ative Enable/Disable, clique em Save e faça um pedido de teste.

6. Informe o nome de usuário e a senha reais do Klarna Merchant Portal, desative Test mode e escolha quando os pedidos serão capturados (padrão: quando o pedido for enviado).

Ao instalar, o módulo cria dois status de pedido: Awaiting Klarna fraud review e Klarna payment on hold. Nenhum dos dois conta como pago nem envia e-mail. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Klarna Payments > 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: Klarna playground, no real payments. ou LIVE: real Klarna payments. Ela avisa quando o nome de usuário ou a senha do modo ativo está faltando (nesse caso o Klarna fica oculto na finalização de compra) e quando a moeda padrão da loja não é vendida pelo Klarna na região de API selecionada.

Klarna Payments

Enable/Disable: Enable Klarna Payments 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 de compra. É também o nome do método de pagamento gravado no pedido. Padrão: Klarna. Obrigatório.

Description: o texto mostrado ao cliente acima do widget do Klarna. Padrão: Pay now, later or in instalments with Klarna.

Credenciais de API

As credenciais de API do Klarna (nome de usuário e senha) são criadas no Klarna Merchant Portal (portal.klarna.com) em Settings > Klarna API credentials. As credenciais de teste vêm do portal do ambiente de testes: playground.eu.portal.klarna.com para a Europa, playground.us.portal.klarna.com para a América do Norte e a Oceania.

Test mode: usa o ambiente de testes do Klarna (credenciais de teste, sem pagamentos reais). Padrão: ativado. Enquanto o modo de teste estiver ativo, o cliente verá TEST MODE: Klarna playground, no real payment is made. abaixo do método de pagamento. Os pedidos mantêm o ambiente em que foram feitos: capturas e reembolsos de pedidos de teste sempre usam as credenciais de teste.

API region: a região da sua conta de comerciante no Klarna. Os clientes só podem pagar com o Klarna a partir dos países dessa região, na moeda do próprio país. O país é obtido do endereço de cobrança do carrinho.

Live username (UID): o nome de usuário da API de produção, por exemplo PK12345_abcdef012345.

Live password: a senha da API de produção (segredo compartilhado).

Test username (UID): o nome de usuário da API do ambiente de testes.

Test password: a senha da API do ambiente de testes (segredo compartilhado).

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

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

Gestão de pedidos

Um pedido realizado no Klarna é uma autorização: o cliente só é cobrado quando o pedido é capturado. Autorizações não capturadas expiram, normalmente após 28 dias, então envie os pedidos a tempo ou use a captura automática.

Capture: quando o cliente é cobrado. Os reembolsos só são possíveis para valores capturados.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Padrão: ativado.

Notificações

O Klarna informa o resultado da verificação de fraude (pedidos enviados como "pending") para o endereço mostrado em Notification URL. Com URLs amigáveis, ele fica assim: https://your-shop/module/wcp_klarna_payment/notification, possivelmente com um código de idioma como /en/. A URL é enviada automaticamente com cada pedido, então não há nada a configurar no Klarna. O conteúdo da notificação nunca é considerado confiável: cada notificação é verificada com a Klarna Order Management API, usando as credenciais do ambiente e da região em que o pedido foi feito, e o pedido no Klarna precisa se referir ao carrinho desta loja. O módulo age de acordo com o que o Klarna informa:

Se o Klarna aceitar uma compra depois que você cancelou ou reembolsou o pedido, o pedido não é reaberto e a autorização do Klarna é liberada. A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

Avançado

Debug log: registra as chamadas à API e os eventos de pagamento em logs/wc_kl_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados. O log nunca contém credenciais, tokens de autorização nem dados de clientes. Padrão: desativado.

Log: mostra o tamanho e as últimas entradas do log, com um botão para limpá-lo.

Uninstall: ao desinstalar o módulo, apaga as configurações do módulo e o log. Os dados dos pedidos (IDs de pedidos no Klarna, reembolsos) são sempre mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Klarna, com o selo do Klarna), e o widget do Klarna é carregado dentro da etapa de pagamento. O módulo cria a sessão do Klarna a partir do carrinho, no servidor. No widget, o cliente escolhe pagar agora, pagar depois ou parcelar, conforme o Klarna oferecer. Quando o cliente faz o pedido, a sessão do Klarna é primeiro atualizada com o carrinho final, e o Klarna autoriza a compra no widget. Em seguida, o módulo cria o pedido no Klarna do lado do servidor, com as linhas, os totais e os endereços do carrinho. Os descontos do carrinho são enviados ao Klarna como uma linha separada. Nenhum pedido existe antes da resposta do Klarna.

O resultado depende do status de fraude do Klarna:

Se o Klarna não puder aceitar o pedido, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Klarna could not accept this order. Please check your billing details or choose another payment method., Klarna did not respond. Please try again in a moment. ou, quando a autorização expirou, uma solicitação para clicar em "Place order" de novo. Os detalhes são gravados no log. Se o país e a moeda de cobrança do cliente não corresponderem a um mercado do Klarna da sua região, o cliente vê Klarna is not available for your billing country and currency. Please choose another payment method.

Clicar duas vezes nunca cria um segundo pedido no Klarna para o mesmo carrinho. Se o carrinho mudar enquanto o Klarna responde, por exemplo em outra aba do navegador, o pedido é criado como Klarna payment on hold com uma nota. Se o Klarna aprovou a compra mas o pedido não pôde ser criado, o cliente vê Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. A próxima tentativa ou a notificação do Klarna cria o pedido a partir do pedido do Klarna armazenado, sem uma nova autorização.

O pedido no Klarna Merchant Portal leva o número do carrinho como referência do comerciante, porque o pedido do PrestaShop ainda não existe quando é feito.

O módulo não tem Klarna Checkout (KCO, substituição completa da finalização de compra), botões do Klarna Express Checkout, On-site messaging ou Sign in with Klarna, nem assinaturas ou métodos de pagamento salvos, e nenhuma captura parcial por linha de pedido. As linhas do pedido não são enviadas de novo ao Klarna quando você edita um pedido depois de feito.

Pedidos e reembolsos

Order statuses

No order yet: o cliente não concluiu a autorização do Klarna, ou o Klarna recusou a compra. Só o carrinho existe.

Payment accepted: o Klarna aceitou a compra. O pagamento é registrado com o ID do pedido no Klarna como ID da transação, e uma nota privada mostra o ID do pedido no Klarna e quando ele será capturado.

Awaiting Klarna fraud review: a compra aguarda a verificação de fraude do Klarna. A notificação do Klarna move o pedido para Payment accepted, Payment error ou Canceled.

Klarna payment on hold: o Klarna devolveu um status de fraude inesperado, ou o valor ou a moeda informados pelo Klarna não conferem com o pedido. A nota explica o motivo. Verifique o pedido no Klarna Merchant Portal.

Payment error: o Klarna recusou ou interrompeu a compra após a verificação de fraude. Não envie o pedido.

Canceled: você cancelou o pedido, ou o Klarna informa que o pedido no Klarna foi cancelado, expirou ou foi encerrado. Com Cancellation ativado, cancelar um pedido ainda não capturado também cancela o pedido no Klarna e libera a autorização, então o cliente não é cobrado. Um pedido já capturado não é cancelado no Klarna: reembolse-o para devolver o dinheiro.

Refunded: o valor capturado foi totalmente reembolsado pelo módulo.

Capture

Com When the order is shipped, mudar o pedido para um status de envio captura o total do pedido antes de o novo status ser salvo. Se o Klarna recusar a captura, por exemplo porque o total do pedido passou do valor autorizado depois de uma edição, o status não muda, nenhum e-mail é enviado e o motivo aparece na página do pedido e em uma nota: o cliente NÃO foi cobrado. Resolva o problema e altere o status de novo para tentar outra vez, ou capture no Klarna Merchant Portal e mude Capture para manual. No PrestaShop 8 em modo de produção, o back office pode salvar o status mesmo assim; nesse caso o módulo define Klarna payment on hold no lugar, com uma nota, para que o pedido nunca apareça como enviado sem a captura. Uma captura bem-sucedida adiciona uma nota com o valor capturado e o ID da captura.

Bloco Klarna payment

A página do pedido mostra um bloco Klarna payment com o ID do pedido no Klarna, o ambiente e a região dele, um selo Playground para pedidos de teste, o status de fraude e o status do Klarna, o valor autorizado, os valores capturado e reembolsado e o histórico de reembolsos.

Reembolsos

No bloco Klarna payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Klarna. Confirme a pergunta Refund this amount through Klarna? This cannot be undone. Reembolsos totais e parciais são aceitos para valores capturados, até o que o Klarna informa como capturado menos o que já foi reembolsado. É preciso ter permissão para editar pedidos; o acesso aos módulos não é necessário. O reembolso é enviado ao ambiente e à região em que o pedido foi feito, então as credenciais desse ambiente precisam estar preenchidas. Se o Klarna não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso no Klarna. Um reembolso total muda o pedido para Refunded; um reembolso parcial não altera o status. Um reembolso repetido nunca é feito duas vezes.

Um pedido que ainda não foi capturado não pode ser reembolsado: cancele-o para liberar a autorização. Com Capture em manual, a loja não sabe o que você capturou no Klarna Merchant Portal. O formulário de reembolso é mostrado com o valor vazio, e o Klarna confere o valor quando você envia.

O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pelo Klarna. Reembolsos feitos no Klarna Merchant Portal não são adicionados ao bloco, mas contam no valor que o Klarna ainda permite reembolsar.

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 Klarna Payments é o primeiro bloco da página Modules > Module Manager > VibeFox Klarna Payments > Configure, acima das configurações. Informe 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 aparecem a linha Product: presta-payment-klarna e o link Manage licenses and domains in your account, que abre a sua conta em 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 em vibefox.net.

Sem uma chave ativa, o Klarna não é mostrado aos clientes na finalização de 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 pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: as notificações do Klarna continuam sendo processadas, e os pedidos ainda podem ser capturados, cancelados e reembolsados.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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 Klarna não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se as credenciais do modo ativo estão preenchidas: nome de usuário e senha de teste no modo de teste, e as reais no modo live. A página de configurações mostra um aviso quando faltam. O país de cobrança do cliente precisa ser um país do Klarna da sua API region, e o cliente precisa pagar na moeda desse país (por exemplo, um cliente da Suécia deve pagar em SEK). Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo de clientes.

O pagamento foi feito, mas o pedido continua em Awaiting Klarna fraud review: a compra aguarda a verificação de fraude do Klarna, e o pedido é atualizado quando a notificação do Klarna chega. Verifique se a sua loja consegue receber as requisições do Klarna no Notification URL exibido nas configurações, e se as credenciais do ambiente em que o pedido foi feito ainda estão informadas. Ative o Debug log e veja o campo Log na página do módulo.

A notificação responde Not configured: faltam as credenciais do ambiente (teste ou live) em que o pedido foi feito, então a notificação não pode ser verificada. Informe-as. O Klarna tenta a notificação de novo.

A notificação responde Verification failed: não foi possível ler o pedido do Klarna pela Order Management API. O Klarna tenta a notificação de novo.

A notificação responde Busy: o pedido estava sendo atualizado por outra requisição no mesmo momento. O Klarna tenta a notificação de novo.

A notificação responde mismatch_ref ou Unknown order: o pedido do Klarna não se refere ao carrinho desta loja, ou o módulo não o conhece. O pedido não é alterado.

O widget não carrega: o cliente vê Klarna could not be loaded. Please try again or choose another payment method. ou Klarna is not available for this purchase. Verifique as credenciais do modo ativo e o país e a moeda do cliente.

A mudança de status para Shipped é recusada: a captura no Klarna falhou. Leia o motivo no bloco Klarna payment ou na nota. O total do pedido pode exigir mais do que o ainda autorizado, o pedido no Klarna pode ainda não ter sido aceito, ou a autorização pode ter expirado. Corrija o problema e altere o status de novo, ou capture no Klarna Merchant Portal.

O reembolso falha: leia a mensagem no bloco. O pedido pode ainda não estar capturado (cancele-o nesse caso), o valor pode exceder o que ainda pode ser reembolsado, ou as credenciais do ambiente do pedido podem estar faltando.

O cliente vê This order is already being paid: outra requisição para o mesmo carrinho está em andamento, por exemplo um clique duplo. Aguarde um momento e verifique se o pedido foi criado.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Klarna Payments e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Uninstall estiver ativado na seção Advanced, as configurações do módulo, o log e as sessões temporárias do widget são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os pedidos e reembolsos do Klarna e os status de pedido Awaiting Klarna fraud review e Klarna payment on hold são sempre mantidos, então pedidos feitos antes podem ser capturados e reembolsados depois de uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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