APP Payments - Documentação Oficial

Info: consta no canto inferior direito do vídeo a informação 'v1.0.0' - que representa a versão atual da aplicação demonstrada no vídeo. O vídeo em questão também ilustra essa versão (v1.0.1) por não ter nenhuma alteração em todo seu processo, apenas pequenas correções foram feitas!

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

Adicionado

• Adicionado ao ZIP da aplicação, a pasta com os arquivos que devem ser incluídos em projetos Charme Fitness

Corrigido

• Corrigidos os status da compra no arquivo de retorno do Gateway Mercado Pago e Paymee

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

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

• Baixe a versão v1.0.1 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! Você não precisa fazer mais nada :) 

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

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 #84 a #86:
  • 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 #89 a #91:
  • 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 #65 e #66:
  
  • 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 #69 e #70:
  • 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 #106 e #107:
  • PAYMENT_PAYMEE_SANDBOX_KEY
  • PAYMENT_PAYMEE_SANDBOX_TOKEN

AMBIENTE PRODUCTION

Documentação em desenvolvimento - estarei no suporte para ajudar você neste processo ...

Integração disponível a partir da Versão 1.1.0

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:

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