APP Payments - Documentação Oficial

Essa aplicação tem como objetivo disponibilizar ao seu cliente final várias opções e taxas para suas vendas! Com ela, você tem nativamente mais de uma opção de integração com Gateway de Pagamentos. Ou seja, seu cliente pode ter várias opções de taxas e escolher a que mais se encaixa no seu negócio.

E tem mais, além de um checkout para e-commerce, com essa aplicação você também consegue fazer a venda de cursos, seguindo um checkout próprio para venda de cursos do EAD!
Como todos sabem, a venda de cursos nativa do workcontrol acontece apenas via HotMart, mas nem todos os negócios acontecem por lá e o seu cliente precisa de mais opções para vender seus cursos! Pensando nisso, essa aplicação disponibiliza um checkout para venda de cursos totalmente isolada, integrado com as opções de pagamentos!

Lembrando que: a ação de alternar entre os Gateways de Pagamento é função do administrador do projeto, logo, o cliente final não precisa e nem deve ter essa autonomia! Quem define as taxas e negocia-as com o cliente é você (administrador) - ou seja, quanto menor a taxa (Gateway usado), melhor para o cliente, e consequentemente maior o valor de seus serviços!

Principais características da aplicação:

• Checkout isolado para e-commerce
• Checkout isolado para EAD
• No Checkout de venda de Cursos EAD, foram retiradas as seguintes etapas e ações do checkout:
  • Botões para aumentar ou diminuir quantidade de produtos: como está sendo feita a venda de um curso essa ação não é necessária
  • Ação de selecionar Frete: Não é feita a entrega de nenhum produto físico, portanto selecionar o frete não é necessário (ainda é solicitado o endereço para informá-lo aos Gateways, mas o frete não é solicitado)
• Correção nativa do problema de fretes com correios (para checkout e-commerce)
• Alteração fácil de Gateway via configurações do sistema, onde ao alterar um parâmetro, outro Gateway é usado!
• Isolamento lógico de Gateways de forma que, infinitos Gateways possam ser usados no checkout. Você mesmo pode fazê-lo

O que há de novo na v1.2.0

Adicionado

• Adicionado novo método de pagamento via PIX no Gateway Mercado Pago
• Adicionado parâmetro PAYMENT_SPLIT_NUM no Gateway PagSeguro para controlar e deixar dinâmica a quantidade máxima do parcelamento via Cartão de Crédito

Corrigido

• Corrigido bug onde ao emitir um boleto pelo Gerencianet e, caso PagSeguro estivesse como recebedor via cartão, criava-se dois boletos: um no PagSeguro e outro no Gerencianet [Report by Alan Matos]
• Corrigido estilo da assinatura dos emails disparados pelo checkout, onde a fonte "Arial" não era aplicada corretamente, deixando o email com a assinatura com a fonte diferente do restante do email
• Corrigido e revisado retorno do Gateway PagSeguro, onde ao receber o código de retorno era dado um "explode" indevido, quebrando o ID e impossibilitando a busca pelo pedido no banco [Report by Claudio Consulim]

Esteja ciente que não podemos prever outras versões do WorkControl criadas e/ou disponibilizadas por você ou por outros profissionais! Caso tenha um WorkControl customizado e não tem conhecimento necessário para adaptação, você deve solicitar suporte para quem disponibilizou a customização para que possa instalar e usufruir essa aplicação!

Esta versão é compatível com as seguintes variações do WorkControl:

• WorkControl v3.1.4
• Projeto Charme Fitness v2.1
• PHP 7.2.+

Prossiga nas etapas abaixo APENAS se você já tiver instalado a versão 1.1.1 no seu projeto. Caso não tenha a versão anterior e queira apenas instalar a aplicação do zero, pule direto para o próximo tópico: Configurações Iniciais

Atualização de Arquivos

Passo 1)

Nenhuma alteração refletiu no arquivo _app/Config/Custom.inc.php - então pode-se manter o mesmo da versão 1.1.0

Passo 2)

Precisamos apenas atualizar o widget do seu projeto! Para fazer isso, siga o procedimento abaixo:

• Baixe a versão v1.2.0 na Área do Cliente clicando no botão de download (ou clique aqui)
• Realize a extração do ZIP, acesse o diretório e copie a pasta /payments
• Vá até o seu projeto, e substitua a pasta copiada no caminho _cdn/widgets/aqui

Pronto!

Agora sua aplicação está atualizada! Os passos a seguir servem em casos de instalações do zero, então, você pode ir para os testes!

A aplicação conta com alguns Gateways configurados e prontos para uso. Abaixo você confere a disponibilidade de cada Gateway em cada método de pagamento

Arquivo /_app/Config.inc.php (a partir da linha #112 do WC original).
Adicione somente o conteúdo em negrito no arquivo, conforme abaixo:

(...)
require 'Config/Config.inc.php';
require 'Config/Agency.inc.php';
require 'Config/Client.inc.php';
// APP PAYMENTS
require 'Config/Custom.inc.php';

Importante: Caso você já tenha instalado alguma outra aplicação comprada aqui no meu market e o require para esse arquivo Custom.inc.php já existir, você não precisa (e não deve) chamá-lo novamente neste local... O que você precisa fazer é copiar o conteúdo do novo arquivo e mesclar com o conteúdo existente!

REMOVENDO FUNÇÃO NATIVA

Arquivo /_app/Config.inc.php (a partir da linha #259 do WC original).

function getShipmentTag($Tag = null)
{
    * Conteúdo da function
}

** Importante: você precisa comentar ou remover essa função desse arquivo. Ela é substituída pela função disponibilizada por Elisandro Echer, para solucionar o erro do frete via correios que, já está implementada no arquivo Custom.inc.php - parte dessa aplicação! 

Para substituição do checkout nenhum arquivo original do WorkControl é atingido. Ou seja, a aplicação funciona de forma isolada sem depender da pasta _cdn/widgets/ecommerce nativa:

Agora você irá escolher e configurar os Gateways para cobrança no seu projeto.

Configure apenas os Gateways que for usar! Mas antes de tudo verifique na tabela se o Gateway possui compatibilidade com o método.

PASSO 1) Confira a Tabela de Disponibilidade para escolher o Gateway para cada método CLICANDO AQUI

PASSO 2) Configure o(s) Gateway(s) que você vai utilizar

• Setup PagSeguro
• Setup Mercado Pago
• Setup Paymee
• Setup Gerencianet

PASSO 3) Informe o nome do Gateway no método desejado - no arquivo /_app/Config/Custom.inc.php - linha #22 a #25. Siga o exemplo deste arquivo, onde temos as seguintes opções nativas já pré-configuradas (sinta-se livre para alterar):

Caso necessário solicite suporte via Ticket, via Área do Cliente. Estarei disponível para te auxiliar neste processo!

WIDGET APP PAYMENTS

** PARA USUÁRIOS DO CHARME FITNESS - Não é necessário executar essa etapa!! Você pode continuar para o próximo parágrafo "NOVOS MEIOS DE PAGAMENTO"

É necessário alterar a chamada para o widget, retirando o require do e-commerce e adicionando o require dessa aplicação. No seu tema abra o arquivo chamado header.php, que deve ficar em '/themes/seu-tema/inc/header.php' - logo no início do arquivo:

* Código antigo:

require '_cdn/widgets/ecommerce/cart.inc.php';

* Substitua por:

require '_cdn/widgets/' .PAYMENT_BASE_PATH. '/checkout/ecommerce/cart.inc.php';

NOVOS MEIOS DE PAGAMENTO

No WorkControl nativo há uma function que informa os métodos de pagamentos disponíveis. Como nossa aplicação tem mais dois métodos (pix e transferência), precisamos adicioná-los à essa function. 

Arquivo '_app/Config.inc.php' - linha #203 (wc nativo):

function getOrderPayment($Payment = null)
{
  $Payments = [
   1 => 'Pendente',
   101 => 'Cartão de Crédito',
   102 => 'Boleto Bancário',
   103 => 'Transferência',
   104 => 'PIX'
  ];
  if (!empty($Payment)):
    return $Payments[$Payment];
  else:
    return $Payments;
  endif;
}

* Adicione apenas os dois novos parâmetros em negrito listados acima. Não esqueça de colocar uma vírgula no fim da linha #208 antes de inserir os dois novos valores!

ADICIONAR CRON AO SERVIDOR

Para que nossa aplicação faça a atualização dos status de pagamentos e também envie o email ao cliente quando o status de sua compra mude, vamos executar uma Cron que faz esse trabalho pra nós!

A decisão de fazer essa ação via Cron veio da necessidade de centralizar a tomada de decisão em um arquivo só. Ou seja, cada Gateway possui sua URL responsável por receber o Webhook de retorno, mas a alteração do status real da compra, bem como o envio de email para o cliente acontece nessa Cron, portanto, é indispensável a execução dessa Cron no seu servidor!

• Em cPanel
  
  Caso seu projeto possua cPanel, acesse o menu "Cron Jobs":
  
  
  
  Selecione em "Common Settings" a opção Once Per Minute
  
  No campo "Command" adicione o seguinte código:
  

  php /home/account/public_html/_cdn/widgets/payment/Returns.cron.php >/dev/null 2>&1

  ** Substitua account pelo nome do usuário da conta logada no cPanel (você encontra o nome no canto superior direito da tela)
  
  
• Em outros painéis de controle
  
  Se a hospedagem não tiver cPanel, não tem problema... Outras hospedagens permitem a execução de URL's em um intervalo de tempo pré-determinado, o que você precisa configurar é a execução da seguinte URL no menor intervalo possível:
  
  https://seusite.com.br/_cdn/widgets/payment/Returns.cron.php
  
  Solicite suporte da Hospedagem caso necessário! Mas antes de tudo lembre-se: você está hospedando um projeto que fará vendas através de um checkout transparente! Esta URL precisa ser executada e a melhor maneira de fazer isso é via Cron, portanto, procure uma hospedagem confiável e que disponibilize essa opção!

Criação da Conta

É aconselhado criar um e-mail padrão para recebimento de pagamentos como por exemplo pagamentos@site.com. E assim configurar todos os meios de pagamentos nele. Para que o gestor da loja tenha acesso as notificações de e-mail!

• Acesse: https://cadastro.pagseguro.uol.com.br/ 
• Crie uma conta como Vendedor selecionando a opção "Para meu negócio"
• Preencha os dados solicitados (preste atenção aos inputs para criação de PIX automáticos)
• Finalize e ative sua conta

AMBIENTE SANDBOX

• Esteja logado(a) em a sua conta PagSeguro
• Acesse este link para obter seu TOKEN
• Acesse este link para obter sua APP ID e a APP KEY
• Os dados coletados devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #85 a #87:
  • PAYMENT_PAGSEGURO_TOKEN_SANDBOX
  • PAYMENT_PAGSEGURO_APP_ID_SANDBOX
  • PAYMENT_PAGSEGURO_APP_KEY_SANDBOX 

AMBIENTE PRODUCTION

• Esteja logado(a) em sua conta PagSeguro
• Acesse este link para obter seu TOKEN
  • Quando acessar pela primeira vez, seu token aparecerá em um "textarea", copie-o
  • Se caso uma mensagem "Seu token já foi gerado. Por questão de segurança ele não é exibido." você pode clicar em "Enviar por email" ou gerar um novo token.
• Acesse este link para obter sua APP ID e a APP KEY
  • Se caso ainda não tiver nenhuma app adicionada, crie uma nova! Preencha os campos de acordo com a sua aplicação, e no campo URL de notificação informe:
    • https://seusite.com.br/_cdn/widgets/payment/PagSeguro/PaymentReturn.php
• Os dados coletados devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #90 a #92:
  • PAYMENT_PAGSEGURO_TOKEN_PRODUCTION
  • PAYMENT_PAGSEGURO_APP_ID_PRODUCTION
  • PAYMENT_PAGSEGURO_APP_KEY_PRODUCTION

Criação da Conta

É aconselhado criar um e-mail padrão para recebimento de pagamentos como por exemplo pagamentos@site.com. E assim configurar todos os meios de pagamentos nele. Para que o gestor da loja tenha acesso as notificações via e-mail!

• Acesse este link e crie uma conta de Empresa, ou uma conta Pessoal
• Avançe todas as etapas e ative a sua conta.

Obtenção de app id e app key

• Esteja logado(a) em a sua conta Mercado Pago
• Acesse este link para visualizar suas aplicações. Se ainda não possuir nenhuma aplicação, crie uma nova seguindo o modelo abaixo:

Preencha o campo Notifications callback URL substituindo seusite.com.br pelo domínio de seu projeto:
https://seusite.com.br/_cdn/widgets/payment/MercadoPago/PaymentReturn.php

Agora, ative suas credenciais

A clicar em Ativar Credenciais uma nova tela será aberta, basta informar a URL do seu projeto e informar qual categoria faz parte. Confirme e pronto!

AMBIENTE SANDBOX

• Esteja logado(a) em sua conta Mercado Pago
• Acesse este link e clique em alguma das integrações da tela
• Ao abrir uma integração, clique na opção Credenciais de Teste
• Os dados desta tela devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #66 e #67:
  
  • PAYMENT_MERPAGO_SANDBOX_KEY
  • PAYMENT_MERPAGO_SANDBOX_TOKEN

AMBIENTE PRODUCTION

• Esteja logado(a) em sua conta Mercado Pago
• Acesse este link e clique em alguma das integrações da tela
• Ao abrir uma integração, clique na opção Credenciais de Produção
• Os dados desta tela devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #70 e #71:
  • PAYMENT_MERPAGO_KEY
  • PAYMENT_MERPAGO_TOKEN

REQUISITOS PARA PRODUÇÃO

Para ativar o modo de produção, verifique se o projeto possui os pré-requisitos! Você pode conferir acessando https://www.mercadopago.com.br/developers/pt/guides/online-payments/checkout-api/goto-production 

O WorkControl e essa app já preenche grande parte dos requisitos, você só precisa ter em sua página uma política de termos e condições e deve deixar claro que é responsável por todos os dados que são inseridos no seu site. Feito isso, está concluído!

Criação da Conta

É aconselhado criar um e-mail padrão para recebimento de pagamentos como por exemplo pagamentos@site.com. E assim configurar todos os meios de pagamentos nele. Para que o gestor da loja tenha acesso as notificações de e-mail!

DICA para acelerar o processo!

Para acelerar o processo de liberação do ambiente de produção, aconselho entrar em contato pelo Whatsapp: (11) 96161-5995 (Daniel C.). Este é um contato interno da Paymee que pode auxiliar na liberação das contas de seus clientes ... Na minha experiência com clientes e com a minha própria conta, este contato foi essencial para a liberação do ambiente de produção no quesito agilidade e suporte!

AMBIENTE SANDBOX

A Paymee utiliza um método diferente para ambiente sandbox. Nela, você pode testar o ambiente sandbox sem precisar criar uma conta!

• Acesse este link para criar sua conta Sandbox
• Informe o nome do projeto, e um email e confirme!
• Os dados da página que irá carregar devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #107 e #108:
  • PAYMENT_PAYMEE_SANDBOX_KEY
  • PAYMENT_PAYMEE_SANDBOX_TOKEN

AMBIENTE PRODUCTION

Antes de preencher o formulário solicitando o ambiente de produção, opcionalmente você pode seguir a dica acima (DICA para acelerar o processo) - pois, após o preenchimento e envio do formulário pode ser que o processo de liberação demore mais do que o esperado!

Para obter suas credenciais:

• Clique no ícone de engrenagem no canto superior direito da tela
• Clique em "API e WebHooks" - você vai ser direcionado(a) para essa tela:

Preencha o campo URL de notificação substituindo seusite.com.br pelo domínio de seu projeto:
https://seusite.com.br/_cdn/widgets/payment/Paymee/PaymentReturn.php

Habilite as três opções no campo Minhas Notificações para receber os callbacks e tratar o retorno da Paymee

Os dados desta tela devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #111 e #112:

• PAYMENT_PAYMEE_KEY
• PAYMENT_PAYMEE_TOKEN

Criação da Conta

É aconselhado criar um e-mail padrão para recebimento de pagamentos como por exemplo pagamentos@site.com. E assim configurar todos os meios de pagamentos nele. Para que o gestor da loja tenha acesso as notificações de e-mail!

• Baixe o aplicativo do Gerencianet no Google Play ou App Store
• Preencha os campos e finalize o cadastro

Criar uma Aplicação

Depois de criar a conta, faça login no Computador e siga as etapas abaixo para criar uma aplicação. Ela será necessária para obter o Client ID e Client Secret para usar na APP Payments:

• No menu superior, clique em API
• Na página que abrir, acesse o menu "Minhas Aplicações" e depois clique em "Nova Aplicação"
  
  • Opcionalmente você pode usar uma aplicação existente
• Na página de criação da Nova Aplicação, siga o modelo abaixo para configurar sua Nova Aplicação

Após concluir a criação da aplicação, vá até o menu lateral esquerdo, e clique na aplicação que você acabou de criar.

AMBIENTE SANDBOX

Na tela da aplicação, clique na aba "Homologação". Os dados desta tela devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #137 e #138:

• PAYMENT_GERENCIANET_SANDBOX_CLIENT_ID
• PAYMENT_GERENCIANET_SANDBOX_CLIENT_SECRET

AMBIENTE PRODUCTION

Na tela da aplicação, clique na aba "Produção". Os dados desta tela devem ser informados nos seguintes parâmetros, no arquivo /_app/Config/Custom.inc.php - linha #141 e #142:

• PAYMENT_GERENCIANET_CLIENT_ID
• PAYMENT_GERENCIANET_CLIENT_SECRET

INFORMAR ID DA CONTA

• Acesse o menu superior API
• Clique no menu lateral "Identificador de Conta"
• Copie o número identificador da conta, e informe no arquivo /_app/Config/Custom.inc.php - linha #123:
  • PAYMENT_GERENCIANET_ACCOUNT_ID

CONFIGURAR CREDENCIAIS (apenas se usar o PIX do Gerencianet)

Certificados .p12 são necessários para a geração do PIX no Gerencianet. A partir daqui vamos criar e inserir os certificados no projeto.

• Acesse o menu "API"
• No menu lateral, clique em "Meus Certificados"
• Selecione uma aba "Produção" ou "Homologação" - cada ambiente terá um certificado, e você deverá emitir os dois certificados (Produção e Homologação) - basta selecionar a aba e repetir o processo
  
  
• Clique em Novo Certificado
• Na modal que aparecer, preencha o nome da aplicação e clique em Gerar Certificado
• ATENÇÃO: Não feche a modal! Clique no botão "Baixar Certificado" para fazer download do seu certificado .p12 - salve em um local seguro (seu certificado possui dados sensíveis)!

Repita o processo para ambos os ambientes (Produção e Homologação) pois precisamos de um certificado para cada ambiente. Agora, precisamos converter os dois certificados para o formato pem, que será aceito e utilizado na APP Payments!

Há várias formas de fazer essa conversão, vai depender de qual sistema operacional você está utilizando! Deixo algumas dicas abaixo de como você poderá fazer isso:

• No Gerencianet, crie um ticket de suporte solicitando a conversão (Menu > Ajuda > Tickets)
• Converta o arquivo seguindo as instruções do próprio Gerencianet (https://dev.gerencianet.com.br/docs/api-pix#section-convers-o-chave-p12-para-chave-pem) 

Inserindo Credenciais na APP Payments

Com os dois certificados convertidos, renomeie-os para o seguinte:

• production.pem - para o certificado do ambiente de produção
• sandbox.pem - para o certificado do ambiente sandbox

Mova os dois arquivos para o caminho: _cdn/widgets/payment/Gerencianet/library/GerencianetAPI/cert/aqui

Configurando Chave PIX

A Gerencianet irá vincular seus recebimentos a uma Chave PIX pré configurada por você. Portanto, é necessário criar uma Chave PIX dentro do Aplicativo Gerencianet.

• Acesse o Aplicativo Gerencianet
• Faça login em sua conta
• Acesse o Menu > PIX
• Crie uma Chave Aleatória

Informe sua Chave Aleatória no arquivo /_app/Config/Custom.inc.php - linha #124:

• PAYMENT_GERENCIANET_PIX_KEY

Essa aplicação é compatível com o projeto Charme Fitness v2.1, comercializado por Alisson P. Santana.

Todas as etapas do checkout permanecem as mesmas, visto que o projeto Charme possui algumas diferenças, comparando-o com o motor original do WorkControl. Então no checkout o que muda é apenas a etapa do pagamento da compra, mantendo-se todo o restante do processo.

Para implementar o checkout, você precisa seguir todos os passos descritos acima para configurar corretamente seus Gateways de recebimento, e também o checkout.

Só depois de seguir as etapas acima é que você pode seguir as etapas abaixo:

Configurar Base Customizada

Algumas ações da APP Payments estão previstas para funcionar no Charme Fitness (v2.1), tais como baixa de estoque quando um pagamento é aceito, dentre outras! Mas para que essas ações sejam previstas, é necessário alterar um parâmetro nas configurações da aplicação:

• Acesse o arquivo _app/Config/Custom.inc.php -
• Navegue até a linha #33 e encontre o define PAYMENT_BASE_CUSTOM
• Altere de 'default' para 'charme-fitness_2.1'
• Pronto! Resete as configurações do painel administrativo WorkControl

Atualizar Arquivos

Para a atualização dos arquivos do projeto Charme Fitness, navegue até a pasta /Compatibilidade Charme2.1 disponível no .zip que você baixou da APP Payments. Em seguida copie e cole a pasta e os arquivos substituindo-os conforme abaixo:

Remover Trecho de Código

Assim como nessa aplicação APP Payments, o Charme Fitness possui a correção da cotação de frete nativo do WC, onde é substituida a função getShipmentTag().

O que precisa ser feito é a remoção completa da função getShipmentTag() do arquivo Custom.inc.php...

• Abra o arquivo _app/Config/Custom.inc.php
• Remova o trecho de código das linhas #235 a #303 - é o trecho de código que representa a função getShipmentTag() - você deve removê-la por completo, pois no Charme Fitness essa mesma função é utilizada, portanto, não é necessária no projeto!

Precisamos fazer a importação das tabelas responsáveis pelo gerenciamento da sua aplicação. Para isso, utilize o seu SGBD padrão ou utilize o seu phpmyadmin

Na raiz da pasta baixada temos o arquivo app-payments_120.sql! Você deve importá-lo para dentro do banco de dados de sua aplicação!

Agora, depois de tudo feito é necessário dar um reset dentro da área administrativa do WorkControl.
Para fazer isso basta ir até Menu > Configurações > Configurações Gerais e clicar no botão Resetar Configurações.

Tudo pronto! Se tudo foi feito como descrito neste tutorial sua Aplicação deve estar funcionando corretamente.