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.
