VibeFox Klarna for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin não é ativado.

PHP: 8.0 ou superior.

HTTPS: o Klarna exige HTTPS para pagamentos reais.

Conta de comerciante no Klarna: você precisa das credenciais de API do Klarna (nome de usuário e senha) da sua conta de comerciante para uma região de API, e das credenciais de teste do portal 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 da loja: 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 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_klarna_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

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

5. Escolha a API region da sua conta de comerciante no Klarna.

6. Insira o nome de usuário e a senha de teste do portal de testes do Klarna, mantenha Test mode ativado, ative Enable/Disable e faça um pedido de teste.

7. Insira o nome de usuário e a senha de produção do Klarna Merchant Portal, desmarque Test mode e escolha quando os pedidos são capturados (padrão: quando o pedido é marcado como Concluído).

Configuração

Todas as configurações estão em uma só página: WooCommerce > Settings > Payments > Klarna Payments. Ao lado do título da página, um selo mostra TEST MODE ou LIVE. A página 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 da loja não é vendida pelo Klarna na região de API selecionada. Na lista de métodos de pagamento, o Klarna aparece como precisando de configuração até que as credenciais do modo ativo sejam informadas, e mostra um selo de modo de teste enquanto o modo de teste estiver ativo.

Geral

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

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Klarna.

Description: o texto exibido 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 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: Use the Klarna playground (test credentials, no real payments). Padrão: ligado. Enquanto o modo de teste estiver ligado, a finalização de compra mostra TEST MODE: Klarna playground, no real payment is made. 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 desta região, na moeda do próprio país.

Europe: Áustria, Bélgica, Finlândia, França, Alemanha, Grécia, Irlanda, Itália, Países Baixos, Portugal, Eslováquia e Espanha (EUR), Suécia (SEK), Noruega (NOK), Dinamarca (DKK), Reino Unido (GBP), Suíça (CHF), Polônia (PLN), República Tcheca (CZK), Hungria (HUF), Romênia (RON). Padrão.

North America (US, CA, MX): Estados Unidos (USD), Canadá (CAD), México (MXN).

Oceania (AU, NZ): Austrália (AUD), Nova Zelândia (NZD).

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

Gestão de pedidos

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

Capture: quando o cliente é cobrado. Reembolsos são possíveis apenas para valores capturados. Se uma captura falhar, o pedido vai para Em espera com uma nota.

When the order is Completed (recommended): captura no envio, marcando o pedido como Concluído (padrão). O valor capturado é o total do pedido menos o que já foi capturado, e nunca mais que o valor ainda autorizado.

Immediately (auto capture): cobra o cliente imediatamente, para produtos digitais ou serviços.

Manually in the Klarna portal: o plugin não captura. Capture o pedido no Klarna Merchant Portal.

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

Notificações

O Klarna informa o resultado de uma verificação de fraude (pedidos registrados como "pending") para a URL de notificação exibida nesta seção. Ela tem este formato: https://your-site/wc-api/wc_kl_payment/. 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 Order Management API do Klarna, e o pedido no Klarna precisa se referir a este pedido da loja. O plugin age de acordo com o que o Klarna informa:

ACCEPTED: o Klarna aceitou a compra. O pedido é marcado como pago após a conferência de valor e moeda.

REJECTED or STOPPED: a compra não passou na verificação de fraude. O pedido passa para Falhou.

Klarna order CANCELLED, EXPIRED or CLOSED: o cliente não foi cobrado. O pedido é cancelado.

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.

Avançado

Debug log: Log API calls and payment events em WooCommerce > Status > Logs, origem wcp_klarna_payment. Erros são sempre registrados. Os logs nunca contêm credenciais nem dados de clientes. Padrão: desligado.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. Os dados dos pedidos (IDs de pedido do Klarna) são sempre mantidos. Padrão: desligado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Klarna) e o widget do Klarna é carregado dentro da finalização de compra. Ali o cliente escolhe pagar agora, depois ou parcelado, conforme o Klarna oferecer. Quando o cliente clica em "Finalizar pedido", o Klarna autoriza a compra no widget. No bloco de Finalização de compra, a sessão do Klarna é primeiro atualizada com o carrinho final, para que mudanças posteriores de frete ou totais não façam o Klarna recusar o pedido. Em seguida, o plugin cria o pedido no Klarna do lado do servidor, com os itens, totais e endereços do pedido do WooCommerce.

O resultado depende do status de fraude do Klarna:

ACCEPTED: o pedido é marcado como pago imediatamente e o cliente vai para a página Pedido recebido. O valor está autorizado e é capturado conforme Capture.

PENDING: o pedido fica em espera até a notificação do Klarna chegar. Não o envie antes.

REJECTED: o pedido passa para Falhou e o cliente vê Klarna could not approve this purchase. Please choose another payment method.

Se o Klarna não puder aceitar o pedido, o cliente vê 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, um pedido para clicar em "Finalizar pedido" novamente. Os detalhes são adicionados às notas do pedido e ao log. Se o país de cobrança e a moeda do cliente não correspondem 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.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.

O plugin 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, métodos de pagamento salvos ou capturas parciais por item do pedido. Os itens do pedido não são enviados de novo ao Klarna quando você edita um pedido depois de feito.

Pedidos e reembolsos

Status do pedido

Processing or Completed: o Klarna aceitou a compra. O WooCommerce define o status usual de um pedido pago. A nota do pedido mostra o ID do pedido no Klarna e quando ele será capturado. O ID da transação é o ID do pedido no Klarna. Quando o pedido é capturado, uma nota mostra o valor capturado e o ID da captura.

On hold: a compra está pendente de verificação de fraude, o Klarna retornou um status de fraude inesperado, o valor ou a moeda informados pelo Klarna não conferiram com o pedido, ou uma captura falhou. As notas do pedido indicam qual.

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

Cancelled: você cancelou o pedido, ou o Klarna informa que o pedido no Klarna foi cancelado, expirou ou foi encerrado. Com Cancellation ligado, cancelar um pedido ainda não capturado 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.

Captura

Com When the order is Completed, marcar o pedido como Concluído captura o total do pedido. Se a captura falhar, por exemplo porque o total do pedido passou do valor autorizado depois de uma edição, o pedido vai para Em espera com uma nota informando que o cliente NÃO foi cobrado, e o cliente não recebe o e-mail de "Pedido concluído". Corrija o problema e marque o pedido como Concluído de novo para tentar outra vez, ou capture no Klarna Merchant Portal.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Klarna Payments. Reembolsos totais e parciais são aceitos para valores capturados, até o valor capturado menos o que já foi reembolsado. O reembolso é enviado ao ambiente e à região em que o pedido foi feito, então as credenciais desse ambiente precisam estar informadas. Se o Klarna não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID do reembolso no Klarna. 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. Reembolsos feitos no Klarna Merchant Portal não são sincronizados de volta ao WooCommerce.

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 > Klarna Payments. 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 de novo, 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 em vibefox.net.

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

Sem uma chave ativa, o Klarna não é exibido 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. Os gerentes da loja conectados continuam vendo 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 de Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: as notificações continuam sendo processadas, e capturas, cancelamentos e reembolsos continuam funcionando.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.

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á ligado e se as credenciais do modo ativo estão preenchidas: nome de usuário e senha de teste no modo de teste, e as de produção no modo de produção. O país de cobrança do cliente precisa ser um país do Klarna da sua API region, pagando na moeda desse país (por exemplo, um cliente da Suécia precisa pagar em SEK).

O pagamento foi concluído, mas o pedido continua On hold: a compra está pendente de verificação de fraude do Klarna, e o pedido é atualizado quando a notificação do Klarna chega. Verifique se o seu site consegue receber requisições do Klarna na URL de notificação exibida nas configurações, e se as credenciais do ambiente em que o pedido foi feito ainda estão informadas. Veja WooCommerce > Status > Logs, origem wcp_klarna_payment.

A notificação responde Not configured: as credenciais do ambiente (teste ou produção) em que o pedido foi feito estão faltando, então a notificação não pode ser verificada. Informe-as.

A notificação responde Verification failed: o pedido no Klarna não pôde ser lido pela Order Management API. O Klarna tenta a notificação novamente.

A notificação responde mismatch_ref: o pedido no Klarna não se refere a este pedido da loja. 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.

Captura falhou, pedido On hold: leia a nota do pedido. O total do pedido pode precisar de mais do que ainda está autorizado, o pedido no Klarna pode ainda não ter sido aceito, ou a autorização pode ter expirado. Corrija e marque o pedido como Concluído de novo, ou capture no Klarna Merchant Portal.

O reembolso falha: leia a mensagem. O pedido pode ainda não ter sido capturado (cancele-o em vez disso), o valor pode exceder o que ainda pode ser reembolsado, ou as credenciais do ambiente do pedido podem estar faltando.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em 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 e exclua-o na página de Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway e os logs (origem wcp_klarna_payment) são removidos somente se Uninstall (Delete the plugin settings and logs when the plugin is deleted) estiver ligado. Caso contrário, ficam guardados para uma reinstalação posterior. Os pedidos existentes mantêm as notas de pagamento e os IDs de transação.

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