Plugin PagSeguro para CakePHP

Veja também em:
http://www.itweb.com.br/blogs/blog.asp?cod=162
Plugin PagSeguro
Sem dúvida, uma das grandes dificuldades quando o assunto é pagamento on-line é a integração com as operadoras de cartões e bancos. Uma das ferramentas disponíveis para quem utiliza esses serviços e que traz vantagens tanto para o desenvolvedor quanto para o cliente ao qual se afilia às operadoras de pagamentos são os Gatways de pagamento. Esses serviços geralmente trabalham com várias bandeiras e bancos, disponibilizando um grande diferencial para pagamento em e-commerces e sistemas que utilizam paramento on-line.
Um Gatway de pagamento muito interessante é o PagSeguro, pertencente ao grupo UOL. Esse serviço se integra a diversos bancos e bandeiras, tornando-se muito simples para o desenvolvedor. Pensando nisso, criei um plugin para o CakePHP que, além de integrar-se, também faz o tratamento dos dados para envio ao PagSeguro.
Instalação
A primeira parte é o download da última versão do plugin que está disponível no Github http://github.com/ftgoncalves/pagseguro. Após realizar o download e colocar o plugin na pasta plugins do CakePHP, basta começar a utilizá-lo.
Utilização
Esse plugin disponibiliza um component e um helper, sendo o componente responsável por transformar e organizar as informações conforme especificações do PagSeguro e o helper por criar o formulário conforme as informações geradas pelo component.
Component
Para utilizar o component, basta declará-lo no controller onde será utilizado:

var $components = array('PagSeguro.PagSeguro');

Isso disponibilizará o component a ser utilizado no controller com 3 métodos. O init, que é obrigatório, tem o objetivo de especificar as informações de configuração da compra. Segue um exemplo com as informações defaults:

$this->PagSeguro->init(array(
'pagseguro' => array(
'e-mail' => 'teste@teste.com',
'reference' => null,
'freight_type' => 'EN',
'theme' => 1,
'currency' => 'BRL'
),
'definitions' => array(
'currency_type' => 'dolar',
'weight_type' => 'kg',
'encode' => 'utf-8'
),
'customer' => array(
'cliente_nome' => null,
'cliente_cep' => null,
'cliente_end' => null,
'cliente_num' => null,
'cliente_compl' => null,
'cliente_bairro' => null,
'cliente_cidade' => null,
'cliente_uf' => null,
'cliente_pais' => null,
'cliente_ddd ' => null,
'cliente_tel' => null,
'cliente_email' => null
),
'format' => array(
'item_id' => 'item_id',
'item_descr' => 'item_descr',
'item_quant' => 'item_quant',
'item_valor' => 'item_valor',
'item_frete' => 'item_frete',
'item_peso' => 'item_peso'
)));

As informações fornecidas são divididas em 4 partes: pagseguro, definitions, customer e format.
Array Pagseguro
Especifica as informações de configuração para o pagseguro, sendo obrigatório o e-mail de cobrança. Caso esse não seja especificado, será gerado um fatal error. O índice reference especifica um código único da compra, geralmente o id da venda. O índice freight_type especifica o tipo de frete utilizado, sendo suportados EN (PAC) e SD (Sedex). Caso você não utilize o sistema de frete ou o mesmo seja gratuito, o recomendado é setar em freight_type com EN e o valor do frete de cada produto para zero reais. O índice theme especifica o tipo de botão utilizado no formulário de envio (estão disponíveis 5 tipos). O índice currency especifica o tipo de câmbio, sendo suportado somente pelo PagSeguro, o BRL. E por último o índice extras, este indica um valor que deve ser acrescentado ou decrementado do valor total da venda.
Array Definitions
É utilizado pelo core do plugin para tratar as informações dos produtos. O índice currency_type especifica como o valor do(s) produto(s) e o valor do(s) frete(s) estão chegando para o plugin. Exemplo:
Caso as informações guardadas no banco de dados estejam com separador de decimal (ponto), no formato americano, então o valor especificado deve ser dolar. Caso esteja com separador de decimal (vírgula), no formato brasileiro, então o valor especificado deve ser real. O índice weight_type especifica a unidade de medida peso. Os dois únicos valores suportados são kg (quilograma) ou g (grama). Este já identifica se o valor fornecido é com separador decimal em vírgula ou ponto. O índice encode especifica o tipo de codificação das strings.
Array Custome
Especifica os dados do cliente, cliente_nome, cliente_cep, cliente_end, cliente_num, cliente_compl, cliente_bairro, cliente_cidade, cliente_uf, cliente_pais, cliente_ddd, cliente_tel e cliente_email. Os índices são obrigatórios e a passagem dos valores opcionais pois caso você não passe o pagseguro fara um pré solicitação das informações do cliente.
Array Format
Este array definirá os significados dos índices e a conversão automática:
Funciona da seguinte forma. Suponha que você tenha o modelo ItemVenda e o mesmo tem os campos id, produto, valor e quantidade. Para especificar o que o plugin deve considerar basta setar:

1
2
3
4
array('format' => array(
'item_id' => 'id',
'item_descr' => 'produto',
'item_valor' => 'valor'));

E assim para todas informações, item_id, item_descr, item_quant, item_valor, item_frete, item_peso. Caso seja acrescentado no array informações que não sejam utilizados pelo pagseguro as mesmas seram descartadas.

Criação de um carrinho de compras
Esta disponível também o método create do plugin pagseguro, este é responsável por organizar e tratar as informações dos produtos. Exemplo:

1
2
3
4
5
6
7
8
9
$this->PagSeguro->create(array(
array(
'item_id' => 1,
'item_descr' => 'Produto A',
'item_valor' => 12.03,
'item_peso' => 1,
'item_quant' => 1,
'item_frete' => 3.50
)));

Obs.: lembrando-se que no campo valor e frete será aplicado a modificação conforme setado em init[definitions][currency_type] e em peso será aplicado conforme init[definitions][weight_type].E por último, o methodo render enviará o array já formatado:

$this->set('datas', $this->PagSeguro->render());

Helper
O helper do plugin é mais simples ainda, seu funcionamento depende das informações geradas pelo component e estão disponíveis 3 métodos. Form, data e submit.

echo $pagSeguro->form($data);

O método form tem como finalidade setar as informações geradas pelo component e escrever a tag html form correto, para envio ao pagseguro.

$pagSeguro->data();

O método data escreve os infindáveis hiddens que sua compra pode ter. Obs não é necessário dar echo.

echo $pagSeguro->submit();

O método submit escreve o botão submit do formulário. Muitas vezes os botões padrões do pagseguro não satisfazem o designer, então é necessário trocar de botão. Para isso basta acrescentar um array de configuração semelhante ao método submit do helper Html. Exemplo:

$pagSeguro->submit(array('src' => '/img/submit.png', 'theme' => false));

Lembrando que o botão vem da configuração do component em definitions theme.
Retorno automático
Para Ativar a funcionalidade de retorno automático basta utilizar os métodos do componente, para isso temos:

$this->PagSeguro->isConfirmation();

Retorna true ou false caso seja POST a solicitação. Lembrando que o PagSeguro acessa esta action 2 veses uma em methodo POST, para envio do estatus da venda e outra de redirecionamento do pagseguro para o site.

$this->PagSeguro->getDataPayment();

Recebe o array já tratado das informações do PagSeguro.

$this->Pagseguro->confirm();

Retorna VERIFICADO ou FALSO ou NADA. Geralmente usado para verificar se o post informado é valido.
Exemplo de uso:

if($this->PagSeguro->isConfirmation()){
$this->PagSeguro->init(array(
'pagseguro' => array(
'email' => 'test@test.com',
'token' => '39839uj3jij3i3jui3uiu3iu3iu3i'
),
'format' => array(
'item_id' => 'id',
'item_descr' => 'description',
'item_quant' => 'amount',
'item_valor' => 'price'
)));
$verificado = $this->PagSeguro->confirm();
if($verificado == 'VERIFICADO'){
$dados_da_venda = $this->PagSeguro->getDataPayment();
//logica
}eles if($verificado == 'FALSO'){
//logica
}else{
//logica
}
//retorno do cliente via site do pagseguro.
}

Obs.: é necessário passar o token no array pagseguro gerado pelo site do pagseguro.
Para gerar o token e ativar a url de retorno: https://pagseguro.uol.com.br/preferences/automaticReturn.jhtml
Pessoal é isso espero ter ajudado, qualquer dúvida estou ai.