Documentação Plugin Cielo para o GiveWP

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

O que é o Plugin Cielo para o GiveWP?

O plugin Cielo API GiveWP é um aplicativo que poder ser instalado diretamente dentro do WordPress, funciona como uma solução de pagamentos para as doações do site. O plugin, 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, QRCode ou PIX. Outro dado importante sobre este plugin, é que ele trabalha de maneira conjunta com uma plataforma da Cielo Ecommerce API 3.0; onde são processados os dados das transações financeiras.O Cielo API GiveWP é um plugin para WordPress que permite receber pagamentos diretamente no GiveWP.

Download do Plugin

Antes de baixar o plugin da Cielo, é necessário adquiri-lo individualmente, como parte do pacote com todos os plugins ou a plataforma de doação completa disponibilizados pela Link Nacional.

Para fazer o download do plugin de integração da Cielo com o GiveWP, acesse a área de cliente da Link Nacional, faça o login e clique no menu Suporte e Downloads:

Dentro da página de downloads, acesse a categoria Plugins WordPress e clique nela.

Clique em Plugin GiveWP Cielo API 3.0 para GiveWP e salve o arquivo no seu computador.

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.

Como instalar o plugin CIELO no WordPress

1. Entrar no painel administrativo do seu WordPress, ex: “www.meudominio.com/wp-admin”;
2. Na barra lateral esquerda acessar o item plugins e depois adicionar novo;
3. Clique na opção enviar plugin e procure no seu computador o arquivo;
4. Após selecionar o arquivo clique em instalar agora;
5. Após a instalação com sucesso clique no botão ativar plugin;
6. Pronto, o seu plugin já está instalado.

A instalação do plugin faz-se dentro do painel administrativo do WordPress do GiveWP. 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.

Ativar Plugin

Após enviar o arquivo do plugin, ele permanecerá desativado por padrão. Portanto, após a instalação, é necessário ativá-lo. Clique no botão Ativar.

Configurar o Plugin Cielo API GiveWP

A configuração é uma etapa essencial para o funcionamento adequado do plugin. Dentro da página de plugins do seu WordPress, é possível acessar as configurações e ajustar diversas opções, que podem variar conforme as atualizações do plugin.

O GiveWP é um requisito obrigatório para o funcionamento do Cielo API. Este plugin não é compatível com o WooCommerce.

Acessando as Configurações

Outra forma de acessar as configurações é pelo menu lateral do WordPress. Basta seguir o caminho: Doações > Configurações > Gateways de pagamento > CIELO API 3.0. Pronto! Você terá acesso às configurações do plugin.

Na página de configurações, é possível realizar todas as configurações do plugin. A tela exibida pode variar ligeiramente e apresentar recursos adicionais, dependendo da versão instalada e das atualizações do plugin.

Campos de Configuração do Plugin

Abaixo estão os principais campos de configuração do plugin Cielo API GiveWP:

• Licença: Insira a chave de licença adquirida em Link Nacional.
• Validar Licença: O botão de validar é utilizado para forçar uma verificação da licença caso ocorra alguma dificuldade na validação. Deve ser usado somente após salvar as configurações.
• Cielo Merchant Id: Chave de identificação do serviço API da Cielo 3.0. Mais informações.
• Cielo Merchant Key: Chave de autenticação do serviço API da Cielo 3.0. Mais informações.
• Descrição da Transação: Defina um nome para que o usuário identifique a cobrança no extrato do cartão. Evite espaços, acentuações e ultrapassar 12 caracteres (exemplo: DoarForm).
• Habilitar Recorrência: Permite cobranças recorrentes automáticas no cartão de crédito, como uma doação por assinatura.
• Descrição da Recorrência: Defina uma mensagem descritiva para a cobrança recorrente.
• Habilitar Recorrência Obrigatória: Se ativado, todas as transações serão processadas como recorrentes obrigatórias.
• Ativar Captura de Transação Automática: Se ativado, as transações serão capturadas automaticamente pela Cielo. Se desativado, toda transação por cartão será pré-autorizada, necessitando ser capturada dentro de 7 dias nos detalhes da doação, caso contrário, o valor será devolvido ao doador. Desativar essa opção pode ser útil para verificações antes da captura do valor.
• Tipo de Ambiente: Escolha entre Sandbox (testes) ou Produção. Esse recurso é normalmente utilizado por desenvolvedores. O ambiente está diretamente ligado às chaves da Cielo utilizadas. Se suas chaves foram fornecidas pela Cielo, o modo deve ser Produção, mesmo para testes de doação.
• Modo de Depuração: Ative para registrar logs e facilitar a resolução de problemas. Esse recurso permite gerar logs das transações, sendo útil para suporte técnico. Sempre que precisar de suporte, será necessário encaminhar os logs de depuração para análise.
• Coletar Detalhes da Cobrança: Habilite para coletar mais informações sobre o doador no formulário de doação.
• Validação de Cartão Online: Se ativado, a bandeira do cartão será validada pela Cielo antes da cobrança (requer ativação da funcionalidade BIN).
• Habilitar Doações Parceladas: Permite que doações acima de R$10,00 sejam parceladas.
• Campo de CVV: Se desativado, o campo CVV não será obrigatório na transação (requer liberação junto à Cielo).

Licença plugin

A primeira configuração é adicionar a licença do plugin adquirida junto à Link Nacional. Essa informação foi enviada para o e-mail de cadastro ou pode ser obtida na área do cliente. Caso ainda não tenha uma licença, solicite uma agora.

Cielo Merchant ID e Merchant Key

Os dois campos seguintes referem-se às credenciais da Cielo API 3.0: Cielo Merchant Key e Merchant ID.

Descrição da Fatura

Este campo define a descrição que aparecerá na fatura do cartão de crédito do doador. Ele deve ser preenchido com até 12 caracteres, sem espaços nem acentuação. Nossa sugestão para o preenchimento desse campo é: DOACAO.

Doação Recorrente (Tipo Assinatura)

Com o recurso de recorrência habilitado, o doador pode optar por transformar a doação em um pagamento recorrente mensal no cartão de crédito. Dessa forma, a doação será debitada automaticamente no cartão do doador a cada mês.

O campo de descrição da recorrência permite personalizar o texto exibido para o doador no momento da seleção da recorrência.

O recurso de recorrência obrigatória torna a doação recorrente uma exigência, ou seja, o doador não terá a opção de fazer uma doação única.

Captura Automática

A opção de habilitar a captura automática de transação faz com que a cobrança no cartão seja realizada de forma automática. Caso essa opção esteja desabilitada, o administrador do site tem até 7 dias para capturar a doação manualmente. Normalmente, esse recurso é mantido desativado para que o administrador possa verificar a veracidade da doação antes de efetuar a captura.

Tipo de Ambiente

Essa configuração define se as chaves (MerchantId e MerchantKey) configuradas no plugin são para o ambiente de Produção ou Sandbox. Atenção: toda chave fornecida pela CIELO é de Produção. A opção Sandbox deve ser habilitada apenas para fins de desenvolvimento. Nunca selecione a opção Sandbox, a menos que você saiba exatamente o que está fazendo.

Modo de Depuração

Esta opção deve ser habilitada apenas para gerar logs, sendo usada em testes e na análise de erros. Não mantenha o recurso habilitado por um longo período.

Validação de Cartão (BIN)

A validação de cartão é um serviço da CIELO denominado BIN, que é útil para verificar se o cartão de crédito está apto a realizar uma transação financeira. Este recurso precisa ser solicitado à CIELO para ativação. Após a liberação, habilite o recurso no plugin.

Doações Parceladas

Ao habilitar este recurso, o doador poderá escolher a opção de parcelamento para o pagamento da doação.

Remover Campo CVV

O campo CVV é composto pelos dígitos de segurança do cartão de crédito. Ao desabilitar essa opção, o doador não será obrigado a inserir essa informação no formulário de doação. No entanto, para que essa funcionalidade funcione, é necessário solicitar a liberação da transação sem o CVV junto à CIELO.

O campo “Quantidade Máxima de Dígitos do CVV” serve como limitador para a quantidade de dígitos que o campo do CVV permitirá inserir.

Detalhes da Cobrança

Ao habilitar os detalhes da cobrança, o formulário legado e multi-step de doação exibirá mais campos para o doador preencher antes de realizar o pagamento. No entanto, essa configuração não se aplica ao formulário de doação visual, pois os detalhes são configurados diretamente no formulário visual.

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:

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:

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.

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