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.