Plugin Cielo API  WooCommerce

Documentação
Informações de configuração do Plugin CIELO API WooCoommerce.

O que é Plugin Cielo API WooCommerce?

O plugin Cielo API WooCommerce é um aplicativo que poder ser instalado diretamente dentro do WordPress, funciona como uma solução de pagamentos para lojas virtuais. O sistema, desenvolvido pela Link Nacional, é uma solução a quem deseja receber à vista ou parcelado com um cartão, seja de crédito ou débito ou PIX. Outro dado importante sobre este plugin, é que ele trabalha de maneira conjunta com uma plataforma da Cielo; onde são processados os dados das transações financeiras.

Quais os tipos de Plugin Cielo WooCommerce?

Há duas maneiras de utilizar o plugin Cielo WooCommerce: a primeira delas é através do plugin grátis Cielo API 3.0 que pode ser baixada e integrada ao WooCommerce. O Cielo API Pro, é um extensão que contém recursos e configuração extras.

Plugin Cielo API Grátis

A versão do plugin Cielo API é a versão gratuita do plugin, que você pode instalar no WordPress com o WooCommerce.

Como atualizar o plugin?

A atualização do plugin faz-se dentro do painel administrativo do WordPress da mesma forma da instalação ou direto pela área de plugins do WordPress clicando em atualizar.

Instalar o Plugin

A instalação do plugin faz-se dentro do painel administrativo do WordPress da sua loja virtual. Para realizá-la, siga os seguintes passos. No painel administrativo do WordPress, acesse a opção Plugin do menu lateral e clique no ícone Adicionar novo ou o botão Adicionar Novo.

Pesquisando pelo plugin

O plugin grátis esta no MarketPlace oficial do WordPress. Dentro da página de plugins, digite Cielo API no campo de pesquisa.

Como Instalar

Em seguida, vá até o plugin e clique no botão Instalar agora.

Ativar Plugin

Por padrão os plugin baixados ficam desativados, sendo assim após instalar o plugin, é necessário ativar, clique no botão Ativar.

Como configurar?

A configuração é uma etapa essencial do processo, pois define o funcionamento adequado do plugin. Dentro do painel de configurações, você encontrará várias opções que podem variar devido às frequentes atualizações do plugin. Vale lembrar que o WooCommerce é um requisito obrigatório para o funcionamento do Cielo API. Siga os passos abaixo para adicionar o plugin Cielo WooCommerce ao seu site:

Acessando as configurações

No menu lateral do WordPress, Clique na opção WooCommerce e depois em configurações.

Dentro da página de configurações do WooCommerce, clique o ítem Pagamentos, do menu principal.

Opções de pagamento

Na página de pagamentos, serão exibidas as formas de pagamento ativadas pelo plugin Cielo gratuito, como cartão de crédito e cartão de débito com autenticação 3DS. Selecione a opção Cartão de Crédito Cielo para configurar esse método de pagamento. A opção PIX esta disponível apenas no plugin Pro.

Configuração cartão de crédito

Nesta etapa, insira as informações solicitadas, como Merchant Key e Merchant ID, que são obrigatórias para o funcionamento do plugin. Dependendo da versão do plugin, podem aparecer configurações adicionais, como limites de parcelas e autenticação 3DS. Certifique-se de revisar todas as opções antes de prosseguir. Após preencher os campos necessários, clique em Salvar alterações.

Cartões de crédito sem autenticação 3DS podem ser configurados para realizar retentativas automáticas em pagamentos recorrentes com erros reversíveis.

Também é possível definir o intervalo em horas entre a tentativa original e a retentativa.

Os cartões de crédito que não utilizam autenticação 3DS podem habilitar a funcionalidade Zero Auth da Cielo. Esse recurso permite validar o cartão antes de realizar a transação, garantindo que apenas cartões válidos prossigam para o pagamento.

Agora é possível salvar o token do cartão na conta do cliente ao realizar pagamentos sem autenticação 3DS.

Cartão de débito e crédito 3DS

Essa modalidade é a opção recomendada de configuração para pagamentos por cartão, pois é muito mais segura. A opção de cartão de débito e crédito tem suporte para transações com e sem autenticação 3DS, o 3DS oferece uma camada extra de segurança para transações online. A principal vantagem dessa funcionalidade é a redução de chargebacks. Retorne à página de pagamentos e clique na opção Cielo – Cartão de Débito e Crédito para ativar essa configuração.

Configuração de cartão de débito e crédito com autenticação 3DS

Para configurar essa opção, você precisará das chaves de autenticação 3DS. Essas chaves devem ser solicitadas junto ao suporte da Cielo, que enviará os seguintes dados:

• Client ID, Client Secret,
• Código do Estabelecimento,
• Código da Categoria do Estabelecimento e
• Nome do Mercador (Estabelecimento).
• As chaves Merchant Key e Merchant ID serão as mesmas usadas na configuração do cartão de crédito ou enviadas pela CIELO no momento de abertura do estabelecimento.

Essas chaves são exclusivas para transações com cartão de crédito e débito com autenticação 3DS e devem ser solicitadas diretamente ao suporte e-commerce da Cielo.

Após concluir a configuração, clique em Salvar alterações.

Atenção: As chaves fornecidas pelo suporte da Cielo são destinadas ao ambiente de Produção.

Cumpridas essas etapas, o plugin Cielo WooCommerce já estará integrado à sua loja virtual e servindo como mais uma opção de pagamento.

Cartão inelegível para autenticação

Alguns cartões no Brasil ainda não têm a funcionalidade de pagamento com autenticação 3DS habilitada. Quando isso acontece, uma mensagem de ‘cartão inelegível’ aparece e a transação não é realizada. No entanto, o plugin da Cielo API possui uma configuração que permite a realização de transações sem autenticação apenas para cartões de crédito, tornando o pagamento disponível também para cartões de crédito sem 3DS.

Captura da transação

No plugin grátis, a captura do pagamento é sempre automática. Já na versão PRO, é possível alterar a configuração de captura para manual ou automática. A opção de captura manual permite que o pedido seja confirmado, mas o administrador da loja virtual tenha tempo para realizar verificações no pagamento antes de completá-lo. Ao selecionar a captura automática, todos os pagamentos serão capturados automaticamente. Caso a configuração seja desabilitada, a captura deve ser realizada manualmente dentro do pedido. O prazo para capturar um pagamento manualmente é de até 12 dias (recomenda-se confirmar essa informação com a Cielo, pois pode estar desatualizada).

A captura manual é útil em situações onde é necessário validar os dados do pedido, realizar uma verificação de fraude ou aguardar algum tipo de confirmação antes de finalizar o pagamento. Exemplos incluem reservas de hotel, compras de produtos perecíveis ou itens que podem se esgotar rapidamente.

Configuração de Parcelamento do Cartão de Crédito

O plugin Cielo API permite configurar o pagamento parcelado com cartão de crédito.

• Na versão gratuita, é possível apenas habilitar o parcelamento básico.
• Na versão PRO, você tem acesso a opções avançadas de configuração de parcelamento.

Para habilitar o pagamento parcelado, basta marcar a opção Pagamentos Parcelados nas configurações do plugin.

Configuração de Parcelamento do Cartão de Crédito (Versão PRO)

Com a versão PRO do plugin, é possível configurar as seguintes opções de parcelamento:

• Parcela mínima: Defina o valor mínimo permitido para cada parcela.
• Juros por parcela: Configure os juros aplicados de acordo com o número de parcelas escolhidas.
• Limite de parcelas: Permite definir um limite máximo de até 18 vezes.

Essas opções garantem maior flexibilidade na configuração de pagamentos parcelados.

Juros por Parcelas

Ao habilitar a opção de juros por parcelamento, é possível definir a taxa de juros individualmente para cada parcela.

Parcelas Máximas Individual por produto  (Versão PRO)

É possível definir o limite máximo de parcelas individualmente para cada produto. A configuração pode ser ajustada diretamente na página de edição do produto. Se o carrinho contiver mais de um produto, as parcelas disponíveis no checkout serão limitadas com base no menor valor de parcela configurado entre os produtos.

Como instalar o Cielo API Pro?

O Cielo API Pro é uma extensão avançada do plugin gratuito. Para instalar o Pro, é necessário que o plugin gratuito já esteja configurado no WordPress e que você tenha adquirido uma licença junto à Link Nacional. A seguir, veja o passo a passo para baixar, instalar e configurar o Cielo API Pro:

Licença da Link Nacional

Após adquirir a licença do Cielo API Pro, acesse a Área do Cliente da Link Nacional e vá até o menu Serviços > Minhas Licenças. Copie o código da licença gerado e guarde-o para utilizá-lo durante a configuração do plugin. Todas as licenças estarão listadas nessa página para fácil acesso.

Na imagem abaixo, há um exemplo de licença. Ao clicar no botão Detalhes, você poderá fazer o download do plugin e verificar o status da licença.

A licença é válida para 1 domínio e 1 site. Se você alterar o site, a localidade de instalação ou o IP do site, será necessário renovar a licença.

Alternativa de download Plugin Pro

Outra forma de obter os arquivos é acessar a área de Downloads na Área do Cliente. A partir daí, você pode baixar a extensão para o plugin Cielo API Pro.

Na área do cliente, acesse o item suporte do menu superior e, em seguida, clique no subitem Downloads.

Na página de Downloads, entre na pasta Plugins WordPress.

Dentro da pasta Plugins WordPress, procure por Plugin WooCommerce Cielo API Pro e faça o download.

Instalando Plugin Pro

Após o download do plugin Cielo Pro, acesse o painel administrativo do seu WordPress. No menu lateral, clique em Plugins e, em seguida, selecione Adicionar Novo.

Na página de instalação de plugins, clique no botão Enviar plugins.

Clique em Escolher o Arquivo e selecione o arquivo que você baixou. Isso habilitará o botão Instalar Agora.

Após escolher o arquivo, clique em Instalar Agora.

Ao fim da instalação, habilite o plugin instalado, clicando no botão Ativar.

Como configurar o plugin Pro?

A configuração do plugin Cielo API Pro começa com a adição da chave de licença. Confira abaixo o passo a passo para realizar essa configuração:

No menu lateral do painel WordPress, acesse o item WooCommerce e clique em Configurações.

Dentro da página de Configurações do WooCommerce, acesse a aba Pagamentos.

Dentro de Pagamentos, acesse os métodos de pagamento: Cielo Cartão de crédito e Cielo Cartão de débito e insira a licença.

A opção Pix está disponível apenas no plugin Pro e não requer um campo de licença para inserção.

Inserir a Licença

Nas páginas de configurações do método de pagamento cartão de crédito e cartão de débito, acesse o campo Licença e insira a chave de licença do plugin, utilize a mesma licença para todos os métodos de pagamento da CIELO.

Clique no botão Salvar alterações para inserir a licença.

A validação da licença só será possível após a inserção da chave e o clique em Salvar Alterações.

A opção Pix está disponível apenas no plugin Pro e não requer um campo de licença para inserção.

Configurando o PIX Cielo no WooCommerce

O primeiro passo é identificar se o PIX encontra-se Autorizado na sua conta dentro da CIELO. Antes de usar o Pix em produção, certifique-se de que o pix está liberado em seu cadastro. Para confirmar basta acessar o portal Cielo na área logada em Meu Cadastro > Autorizações > PIX.

A funcionalidade de pagamento via PIX está disponível exclusivamente na versão PRO do plugin Cielo API para WooCommerce.

Para configurar o PIX:

1. Acesse o painel administrativo do WordPress.
2. Vá até o menu WooCommerce e clique em Configurações.
3. Na aba Pagamentos, localize a opção PIX e clique em Gerenciar.
4. Preencha as informações necessárias, como os dados da sua conta Cielo, e salve as alterações.

Pronto! Agora o PIX estará habilitado como uma opção de pagamento na sua loja WooCommerce.

Para traduções em português do Brasil na página de finalização de compra do PIX, selecione a opção “Forçar tradução PT_BR“

Opções de Configuração

1. Habilitar/Desabilitar: Marque esta opção para ativar ou desativar o meio de pagamento PIX em sua loja WooCommerce.
2. Descrição: Adicione um texto que será exibido ao cliente no momento da geração do PIX.
3. MerchantID: Informe a chave obtida no painel da Cielo API após o credenciamento do estabelecimento junto à Cielo.
4. Merchant Key: Informe a chave obtida no painel da Cielo API após o credenciamento do estabelecimento junto à Cielo.
5. Descrição da Fatura: Insira uma descrição personalizada para facilitar a identificação da compra no extrato bancário do cliente.
6. Status de Pagamento Completo: Defina o status do pedido após a confirmação do pagamento via PIX. As opções disponíveis são: Processando, Aguardando e Concluído.
7. Ambiente: Determine se as chaves inseridas são de produção ou desenvolvimento. Sempre utilize Produção. Utilize Desenvolvimento apenas se estiver usando as chaves MerchantID e Merchant Key do ambiente de SANDBOX da Cielo.

Confirmação de Pagamento PIX

O PIX Cielo possui confirmação automática de pagamento. No entanto, essa confirmação é processada através do CRON do WordPress.

Se o CRON estiver desativado ou não funcionando corretamente, você verá uma notificação solicitando a criação manual do CRON em seu WordPress para garantir o funcionamento da confirmação de pagamentos.

Erro na Geração do PIX QR Code

Caso ocorra um erro na geração do PIX, siga os passos abaixo:

1. Ative os logs de depuração nas configurações do plugin.
2. Clique em Salvar alterações.
3. Realize um novo pedido para gerar o erro novamente.
4. Acesse a opção Ver registros para analisar as informações registradas no log.

Na maioria dos casos, o erro ocorre porque o PIX não está habilitado na Cielo. Se isso acontecer, entre em contato com o suporte da Cielo para regularizar a configuração.

Aba Desenvolvedor do PIX

Na aba Desenvolvedor das configurações do PIX, é possível habilitar a visualização dos logs diretamente nos pedidos. Isso facilita a depuração e resolução de problemas relacionados ao pagamento.

Após utilizar os logs, é recomendável usar a opção Limpar logs dos pedidos para remover quaisquer dados sensíveis armazenados.

Lembre-se de que o modo de depuração deve ser ativado apenas temporariamente, durante a identificação e resolução de problemas com o plugin PIX da Cielo.

WooCommerce Hooks

Os hooks no WooCommerce são pontos de ancoragem que permitem aos desenvolvedores adicionar, modificar ou executar funcionalidades em momentos específicos do fluxo do WooCommerce, sem alterar o código principal do plugin.

lkn_wc_cielo_set_installment_limit

• Tipo: apply_filters

• Descrição: Define o número limite de parcelamento.
• Parâmetros: string $limit = ’12’, AbstractPaymentMethodType $gateway

$limit: Por padrão, o limite é definido como 12, permitindo que o responsável pelo gerenciamento do plugin defina um limite de parcelamento customizado.

$gateway: Informações sobre o pagamento, como merchant_id, merchant_key, tipo de pagamento e outros dados necessários para o processo de validação. Essas informações são obtidas pela instanciação da classe LknWCGatewayCieloCredit() ou LknWCGatewayCieloDebit() na função: initialize().

Exemplo:

add_filter('lkn_wc_cielo_set_installment_limit', function($limit, $gateway) {

$limit = 20;

return $limit;

})

apply_filters('lkn_wc_cielo_set_installment_limit', $limit, $gateway);

lkn_wc_cielo_set_installments

• Tipo: apply_filters

• Descrição: Define o nome da label nas opções.
• Parâmetros: Array $installments = [], AbstractPaymentMethodType $gateway

$installments: Array contendo a lista de opções disponíveis no momento do pagamento.

$gateway: Informações sobre o pagamento, como merchant_id, merchant_key, tipo de pagamento e outros dados necessários para o processo de validação. Essas informações são obtidas pela instanciação da classe LknWCGatewayCieloCredit() ou LknWCGatewayCieloDebit() na função: initialize().

Exemplo:

add_filter(‘lkn_wc_cielo_set_installments’, function() {

$installments[] = array(‘id’ => ‘1’, ‘label’ => $index . ‘x de ‘ . $fomartedNumber);

return $installments;

})

apply_filters('lkn_wc_cielo_set_installments', $installments, $gateway);

Observação: Caso o usuário não defina nenhum valor, o resultado será um array vazio.

Possíveis problemas ao instalar

O plugin não apresenta erros fatais, pois passa por testes rigorosos antes da publicação. No entanto, a falta de recursos do seu provedor de hospedagem pode resultar em alguns problemas conhecidos. Abaixo estão dois itens obrigatórios para o funcionamento do plugin Pro:

1. Verifique a versão do PHP; teste tanto em uma versão mais recente quanto em uma versão anterior.
2. Certifique-se de que a biblioteca IONCUBE esteja instalada em sua hospedagem. Para ativá-la, acesse as configurações do seu PHP e habilite o recurso.
3. Ative o recurso de depuração para analisar os logs de erros.

Logs de erros das transações

Para identificar erros, recomenda-se habilitar a verificação dos logs de erro. No entanto, utilize essa configuração apenas para esse fim, mantendo-a sempre desabilitada para garantir a privacidade dos dados. Para habilitar os logs de depuração, acesse as configurações do plugin e ative a opção Habilita a captura de logs para pagamentos. Siga os passos abaixo para configurá-la:

1. Dentro do painel administrativo do WordPress, acesse o menu lateral, clique no item WooCommerce e, em seguida, no subitem Configurações;
2. Na página das configurações do WooCommerce, entre na aba Pagamentos;
3. Na aba pagamentos, existem as opções Cartão de crédito e Cartão de débito. Para as duas o procedimento é o mesmo. Faço-o primeiro em uma das opções e depois na outra;
4. Dentro da página de configurações da opção de pagamento (Cartão de crédito/débito), acesse e marque o campo Depuração: habilita a captura dos logs para pagamentos;
5. Para finalizar, clique no botão Salvar alterações.

Logs de erros das transações no pedido

É possível visualizar o log da transação diretamente na página de detalhes de cada pedido no WooCommerce. Essa funcionalidade foi adicionada para facilitar o acompanhamento e a análise das transações relacionadas a cada pedido, oferecendo maior controle ao administrador. Esse recurso fica disponível apenas se a configuração de Depuração estiver habilitada.

Uma vez que a opção responsável pela captura dos logs das transações esteja ativada (Depuração), realize uma nova transação para gerar o log. Você pode visualizar facilmente todos os logs de transações realizadas em seu site. Confira este breve tutorial para entender como acessar os logs das transações:

1. No painel administrativo do WordPress, vá até o menu lateral, acesse o item WooCommerce e, em seguida, o subitem Status;
2. Na página de Status do plugin, acesse a aba Logs;
3. Dentro da aba Logs, haverá então uma tabela com todos os logs das transações realizadas. Você, pela data, consegue identificar o log de uma transação determinada e acessá-lo clicando no botão Visualizar, que fica na última coluna, no lado direito da página .

Erro de Credenciais Inválidas (ReturnCode 002)

Caso no log de transações apareça o erro “Credenciais Inválidas” com o ReturnCode 002, é necessário entrar em contato com a CIELO e reportar o problema. Esse erro geralmente ocorre devido a um problema no cadastro do seu estabelecimento junto à CIELO.

Recomendamos verificar com a CIELO as informações cadastradas para garantir que tudo esteja correto. Esse passo é fundamental para garantir que a integração com o plugin funcione corretamente.

Códigos de Retorno

Toda transação possui um código de retorno, e cada código indica uma situação ou dificuldade específica na transação. Alguns desses códigos podem ser ajustados ou corrigidos, enquanto outros indicam problemas que não podem ser resolvidos diretamente pelo usuário.

Para mais detalhes sobre cada código de erro e como solucioná-los, consulte nossa página dedicada, disponível em: Códigos de Retorno API 3.0