sexta-feira, 28 de dezembro de 2012

Integração com PagSeguro Parte 2

1. Implementando a integração


A API do PagSeguro é simples e fácil de usar e dentro do zip que se encontra para download, existe uma pasta com quatro sources de exemplos.



Esses exemplos contemplam tudo que é preciso para usar o PagSeguro e o maior trabalho mesmo é criar suas rotinas para executar o pagamento a partir de sua venda.

Para todas as rotinas da API, será preciso utilizar o email cadastrado no PagSeguro e o token de segurança que eu comentei no post anterior.

1.1 Criando o Pagamento


Ao abrir o CreatePayment.java você perceberá que realmente é simples realizar este procedimento e o maior trabalho vai ser adequar seu negócio pois, o PagSeguro pede informações que talvez você não tenha ou não esteja em um formato aceito.

O PagSeguro fez uma serie de validações dos dados enviados e vai lançar mensagens de erro indicando o que não passou na validação.

Por causa destas validações, eu tive de modificar meu sistema. Um dos pontos mesmo que ele acusa problema é com o nome de pessoa, que possui um tamanho minimo.

Por causa destas validações é bom realizar testes com os dados mínimos obrigatórios em seu sistema e verificar se algum dado deve se tornar requerido.

A lista com todas as mensagens de erro pode ser vista neste link: https://pagseguro.uol.com.br/v2/guia-de-integracao/codigos-de-erro.html#rmcl.

Para relacionar uma venda sua com uma transação do PagSeguro existe o método: paymentRequest.setReference("REF1234");

Isto é muito importante pois é com esta informação que você conseguirá descobrir para qual venda aquele pagamento se relaciona. É um campo string e eu recomendo utilizar o próprio Id da venda.

1.2 Processando as notificações


Como eu comentei no outro texto, é preciso ter uma página em seu sistema que será acessada pelo PagSeguro. Está página receberá códigos de notificação e a partir destes códigos se obtêm os dados da transação.

O código da notificação é passado com o parâmetro notificationCode e depois de capturar este valor da requisição deverá ser usado o código da classe ReceiveNotifications.java.

Com este código você consegue obter o ID da transação e status e deve obter o resto das informações acessando os dados da transação usando o código da classe SearchTransactionByCode.java.

Na prática sua venda, deverá receber um status de Aguardando Pagamento e este status será modificado pela rotina que processa as notificações.

Mais informações sobre todo o processo podem ser obtidas aqui: https://pagseguro.uol.com.br/v2/guia-de-integracao/tutorial-da-biblioteca-pagseguro-em-java.html.

2 Armazenando os dados


Eu decidi armazenar todos os dados das transações do PagSeguro para minhas vendas. Deste modo eu não preciso acessar o PagSeguro via API todas as vezes que precisar de alguma informação.

Isto também fica prático pelo fluxo do PagSeguro. Como o sistema é notificado quando existe inserção/atualização nas transações neste momento além de atualizar o status de sua venda, eu recomendo que você grave todos os dados desta transação.

Não são muitos dados e abaixo pode ser visto o DER do schema pag_seguro que eu criei.


Criei as tabelas em inglês, porque mesmo o PagSeguro sendo usado apenas no Brasil, sua API é toda em inglês.

As tabelas tb_transaction_status, tb_payment_method_code e tb_payment_method_type são tabelas com os códigos que o PagSeguro utiliza. Populei elas com base nos dados da documentação e servem para visualização mais fácil do que cada código representa.

Para facilitar a vida de vocês seguem os inserts para popular estas tabelas:

 
INSERT INTO tb_payment_method_code VALUES (101, 'Cartão de crédito Visa');
INSERT INTO tb_payment_method_code VALUES (102, 'Cartão de crédito MasterCard');
INSERT INTO tb_payment_method_code VALUES (103, 'Cartão de crédito American Express');
INSERT INTO tb_payment_method_code VALUES (104, 'Cartão de crédito Diners');
INSERT INTO tb_payment_method_code VALUES (105, 'Cartão de crédito Hipercard');
INSERT INTO tb_payment_method_code VALUES (106, 'Cartão de crédito Aura');
INSERT INTO tb_payment_method_code VALUES (107, 'Cartão de crédito Elo');
INSERT INTO tb_payment_method_code VALUES (108, 'Cartão de crédito PLENOCard');
INSERT INTO tb_payment_method_code VALUES (109, 'Cartão de crédito PersonalCard');
INSERT INTO tb_payment_method_code VALUES (110, 'Cartão de crédito JCB');
INSERT INTO tb_payment_method_code VALUES (111, 'Cartão de crédito Discover');
INSERT INTO tb_payment_method_code VALUES (112, 'Cartão de crédito BrasilCard');
INSERT INTO tb_payment_method_code VALUES (113, 'Cartão de crédito FORTBRASIL');
INSERT INTO tb_payment_method_code VALUES (201, 'Boleto Bradesco');
INSERT INTO tb_payment_method_code VALUES (202, 'Boleto Santander');
INSERT INTO tb_payment_method_code VALUES (301, 'Débito online Bradesco');
INSERT INTO tb_payment_method_code VALUES (302, 'Débito online Itaú');
INSERT INTO tb_payment_method_code VALUES (303, 'Débito online Unibanco');
INSERT INTO tb_payment_method_code VALUES (304, 'Débito online Banco do Brasil');
INSERT INTO tb_payment_method_code VALUES (305, 'Débito online Banco Real');
INSERT INTO tb_payment_method_code VALUES (306, 'Débito online Banrisul');
INSERT INTO tb_payment_method_code VALUES (307, 'Débito online HSBC');
INSERT INTO tb_payment_method_code VALUES (401, 'Saldo PagSeguro');
INSERT INTO tb_payment_method_code VALUES (501, 'Oi Paggo');

INSERT INTO tb_payment_method_type VALUES (1, 'Cartão de crédito');
INSERT INTO tb_payment_method_type VALUES (2, 'Boleto');
INSERT INTO tb_payment_method_type VALUES (3, 'Débito online (TEF)');
INSERT INTO tb_payment_method_type VALUES (4, 'Saldo PagSeguro');
INSERT INTO tb_payment_method_type VALUES (5, 'Oi Paggo');

INSERT INTO tb_transaction_status VALUES (1, 'Aguardando pagamento');
INSERT INTO tb_transaction_status VALUES (2, 'Em análise');
INSERT INTO tb_transaction_status VALUES (3, 'Paga');
INSERT INTO tb_transaction_status VALUES (4, 'Disponível');
INSERT INTO tb_transaction_status VALUES (5, 'Em disputa');
INSERT INTO tb_transaction_status VALUES (6, 'Devolvida');
INSERT INTO tb_transaction_status VALUES (7, 'Cancelada');

Achei importante criar um tabela de histórico das transações, pois assim eu consigo ter um detalhe de quanto tempo a transação passou em determinado status.

Preferi fazer o controle deste histórico via trigger:

 
CREATE OR REPLACE FUNCTION pague_seguro.register_tb_transaction_audit()
  RETURNS trigger AS
$BODY$
    BEGIN
        --
        -- Registrar historico caso tenha mudado o status
        --
        IF (TG_OP = 'INSERT') THEN
   UPDATE pague_seguro.tb_transaction_history set dt_end = now() where cd_transaction = NEW.cd_transaction AND dt_end is null;
            INSERT INTO pague_seguro.tb_transaction_history (cd_transaction, id_transaction_status, dt_begin) select NEW.cd_transaction, NEW.id_transaction_status, now();
            UPDATE pague_seguro.tb_transaction set dt_status_change = now() where cd_transaction = NEW.cd_transaction;
        END IF;
        IF (TG_OP = 'UPDATE') THEN
            IF (NEW.id_transaction_status <> OLD.id_transaction_status) THEN
      UPDATE pague_seguro.tb_transaction_history set dt_end = now() where cd_transaction = NEW.cd_transaction AND dt_end is null;
      INSERT INTO pague_seguro.tb_transaction_history (cd_transaction, id_transaction_status, dt_begin) select NEW.cd_transaction, NEW.id_transaction_status, now();
      UPDATE pague_seguro.tb_transaction set dt_status_change = now() where cd_transaction = NEW.cd_transaction;
     END IF; 
        END IF;        
        RETURN NULL; -- o resultado é ignorado uma vez que este é um gatilho AFTER
    END;
  $BODY$
  LANGUAGE plpgsql VOLATILE
  COST 100;

3. Conclusão


Neste post eu não entrei em muitos detalhes da API, pois ela está bem documentada. Minha intenção passar um quadro geral de como pode ser implementada a integração em seu sistema e dar uma visão do esforço necessário.

Tentei passar as informações que eu gostaria de ter tido conhecimento antes de ter colocado a mão na massa.

Qualquer dúvida eu responderei nos comentários.

quarta-feira, 26 de dezembro de 2012

Integração com PagSeguro Parte 1

Conceito e configuração da conta.


1. Introdução

O PagSeguro é uma solução nacional para pagamentos online mantida pela UOL. Estas soluções visam facilitar a vida de compradores e vendedores e a mais famosa é o PayPal.

Como o Paypal não atuava oficialmente no Brasil, era preciso usar cartão de crédito internacional e acabava dificultando as coisas para quem compra e principalmente para quem vende.

O PagSeguro funciona bem e até agora se provou seguro, tanto para quem compra quanto para quem vende.

O maior defeito do PagSeguro, em minha opinião, é a falta de um Sandbox oficial para testes. Até existem opções criadas por terceiros, mas não são suportadas e a que eu testei nem funcionava mais com a API nova de integração.

Isto não é problema para compradores e vendedores, mas dificulta o trabalho dos desenvolvedores pois torna o teste mais trabalhoso e custoso.

Minha intenção aqui é mostrar, em alguns posts, como eu fiz para integrar um sistema meu com o PagSeguro.

2. Fluxo resumido da operação

O fluxo inicia com o usuário finalizando a compra escolhendo o modo de pagamento PagSeguro. Feito isto a aplicação faz o processamento desta venda utilizando a API do PagSeguro e recebe uma URL.

O sistema deve redirecionar o usuário para esta URL, para que ele possa finalizar o pagamento.

Depois que o pagamento é finalizado o usuário é redirecionado de volta para o sistema de origem e o fluxo das notificações se inicia.

O PagSeguro fará um ou mais POSTs em uma página de seu sistema passando dois parâmetros: notificationcode e notificationtype.

São com estas notificações que o PagSeguro informará a seu sistema o que está acontecendo com a transação.

A página que recebe o post deve utilizar o código da notificação para acessar o PagSeguro via API e obter o status da transação, obtendo várias informações como se o pagamento foi autorizado ou não.

Mais detalhes podem ser vistos neste link: https://pagseguro.uol.com.br/integracao/pagamentos-via-api.jhtml

Outra informação importante é que caso o PagSeguro não consiga enviar os dados da notificação para seu sistema, "o PagSeguro irá envia-la novamente a cada 2 horas, até um máximo de 5 tentativas".

Mas caso seu sistema fique fora do ar por mais tempo é possível obter as informações das transações realizando uma consulta por data: https://pagseguro.uol.com.br/v2/guia-de-integracao/consulta-de-transacoes-por-intervalo-de-datas.html.

3. Configuração da Conta

O primeiro passo é converter sua conta para Vendedor ou Empresa, você vai precisar disto para fazer os testes iniciais. Como não há disponibilidade de um sandbox de testes, será necessário realizar umas compras e depois cancelar.

Depois de converter a conta, será possível acessar o menu 'Integrações' e a primeira configuração será  a 'Pagina de redirecionamento'. 

Essa é a página para qual o cliente será redirecionado depois que finalizar o pagamento no PagSeguro. Eu pessoalmente prefiro o redirecionamento dinâmico, pois em caso de alguma mudança na aplicação, eu não preciso que o cliente reconfigure este parâmetro.

Você vai configurar o nome do parâmetro que o PagSeguro vai utilizar para informar o código da transação. Com este nome, você pode via API buscar as informações sobre esta transação, para informar ao cliente.


O segundo item do menu permite a criação do 'Token de segurança', que será utilizado na autenticação entre o sistema e o PagSeguro. Depois de criado ele fica visível apenas na criação e caso você esqueça ou perca, basta gerar novamente.

No terceiro item é onde ativaremos o 'Pagamento via API'


O quarto item do menu, é o 'Notificação de transações' e será o ultimo a ser configurado. Aqui vamos definir qual página de nosso sistema receberá as notificações sobre as mudanças de status das transações.

Por causa dessa característica, mesmo na fase de desenvolvimento será preciso configurar com uma URL válida. 

Isto é chato e as duas possibilidades que eu vejo são:
1. Utilizar seu servidor local. Para isso é preciso que o PagSeguro tenha acesso externo via internet. Isso pode ser complicado caso você esteja acessando a internet via um roteador ADSL ou proxy.
2. Utilizar um servidor de homologação. No meu caso eu criei uma conta no Amazon EC2 e montei um ambiente de homologação.


Nós primeiros testes, para conseguir debugar com a aplicação rodando localmente, eu iniciava o teste de minha maquina e depois monitorava as notificações que eram enviadas pelo PagSeguro para o meu servidor de homologação.

Eu monitorava logando em um arquivo os dados enviados via GET/POST para a página:

================= 2012-12-07 19:06:52 ==================
notificationcode=1F2964-960Z850D85F6-0BB4T3AFBC5E-2997F0
notificationtype=transaction


Com estes dados em mãos eu posso repassar para meu sistema local, via URL no navegador:

processaNotificacao.wsp?notificationcode=1F2964-960Z850D85F6-0BB4T3AFBC5E-2997F0&notificationtype=transaction

Minha recomendação é que todos os POSTs/GETs recebidos pela página de notificação sejam logados, assim caso não seja processado algo em seu sistema por causa de um bug, o processamento pode ser feito manualmente.

No próximo post eu falarei sobre a utilização da API e sobre a criação de tabelas para guardar em banco tudo que foi processado, realizando um controle melhor e evitando o acesso ao PagSeguro sem necessidade.

[]'s