Guia de Integração

Tutorial da Biblioteca PagSeguro PHP

A biblioteca PagSeguro em PHP é um conjunto de classes de domínio que facilitam, para o desenvolvedor PHP, a utilização das funcionalidades que o PagSeguro oferece na forma de APIs.

Versão: 2.2.1

Baixar agora

Download e instalação

Para instalar a biblioteca siga as instruções abaixo:

  1. Faça o download da Biblioteca PagSeguro em PHP;
  2. Descompacte os arquivos em seu computador;
  3. Dentro do diretório source existem dois diretórios, o examples e o PagSeguroLibrary. O diretório examples contém exemplos de chamadas utilizando a API e o diretório PagSeguroLibrary contém a biblioteca propriamente dita. Caso queira importar somente a biblioteca, faça upload do diretório PagSeguroLibrary e inclua a classe PagSeguroLibrary.php em seu projeto. Essa classe se encarregará de importar todas as funcionalidades da biblioteca no seu sistema.

Credenciais

Visando garantir a segurança dos seus dados no PagSeguro, é necessário que você informe suas credenciais de acesso ao executar funções da biblioteca que realizam chamadas via API.

As credenciais de acesso são formadas pelo e-mail de cadastro no PagSeguro e um token, que funciona como uma senha.

Veja mais informações sobre segurança caso você ainda não tenha gerado o token.

A maneira mais fácil de informar suas credenciais é defini-las no arquivo de configuração da biblioteca. Você também pode informa-las ao fazer chamadas via API utilizando a classe PagSeguroAccountCredentials que é responsável por encapsular suas credenciais.

Funcionalidades

A Biblioteca PagSeguro em PHP é um conjunto de classes de domínio que facilitam o desenvolvedor PHP na utilização das funcionalidades que o PagSeguro oferece na forma de APIs. Com a biblioteca instalada e configurada, você pode facilmente integrar funcionalidades como:

Veja abaixo um tutorial para cada uma dessas funcionalidades. Veja também a documentação das classes da biblioteca.

Criar uma requisição de pagamento

Criar uma requisição de pagamento consiste em fazer uma chamada à API de Pagamentos do PagSeguro, informando os dados de uma compra a ser realizada em sua loja. Esses dados da compra podem ser p.e. os produtos que serão vendidos bem como os dados do comprador que está navegando.

Para informar esses dados, seu sistema deve fazer uma requisição à API de Pagamentos do PagSeguro que irá armazenar os dados e retornar um código de requisição.

Com o código de requisição em mãos, sua loja ou aplicação será capaz de direcionar o comprador ao PagSeguro onde ele realizará o pagamento dos itens previamente informados. Dessa maneira seu sistema irá oferecer maior segurança e flexibilidade, pois os dados do pagamento serão informados via API diretamente pelo seu sistema e não irão trafegar pelo navegador do usuário na internet.

Nesse contexto a classe PagSeguroPaymentRequest da biblioteca é responsável por criar uma requisição de pagamento de maneira prática: você apenas informa os dados do pagamento e logo após executa o método register que lhe devolve a URL necessária para direcionar seu comprador ao ambiente seguro onde ele realizará o pagamento.

Para melhor entendimento, vamos exemplificar a criação de uma requisição de pagamento com o seguinte cenário:

  1. O comprador navega pela loja e decide comprar um notebook no valor de R$ 2.430,00 e uma mochila no valor de R$ 150,99.
  2. Sua loja requisita os dados do comprador, p.e., nome completo, e-mail e telefone bem como os dados do endereço de envio.
  3. Ainda na loja o comprador escolhe pagar com PagSeguro.

Com essas informações em mãos você deve criar um objeto do tipo PagSeguroPaymentRequest:

	$paymentRequest = new PagSeguroPaymentRequest();

Agora você deve adicionar os produtos ao objeto criado:

	$paymentRequest->addItem('0001', 'Notebook', 1, 2430.00);
	$paymentRequest->addItem('0002', 'Mochila',  1, 150.99);

Você também pode adicionar produtos e outros parâmetros indexados utilizando o método addIndexedParameter:

	$paymentRequest->addIndexedParameter('itemId', '0003', 3);
	$paymentRequest->addIndexedParameter('itemDescription', 'Mouse', 3);
	$paymentRequest->addIndexedParameter('itemQuantity', '1',3 );
	$paymentRequest->addIndexedParameter('itemValue', '30.25', 3);

Você também pode informar os dados fornecidos pelo comprador em sua loja, assim, o comprador não precisará informar esses dados novamente no site do PagSeguro:

	$paymentRequest->setSender(
		'José Comprador', 
		'comprador@uol.com.br', 
		'11', 
		'56273440'
	);

Informe o endereço de envio fornecido pelo comprador, assim, o comprador não precisará informa-lo novamente no site do PagSeguro:

	$paymentRequest->setShippingAddress(
		'01452002',	
		'Av. Brig. Faria Lima', 	
		'1384', 	
		'apto. 114',	 
		'Jardim Paulistano', 	
		'São Paulo', 	
		'SP', 	
		'BRA'	
	);

É necessário que você informe a moeda em que o comprador irá realizar o pagamento. No momento, a única opção disponível é BRL (Real).

	$paymentRequest->setCurrency("BRL");

É necessário informar também o tipo de frete da compra, veja mais detalhes na classe PagSeguroShipping:

	$paymentRequest->setShippingType(1);

Caso o seu sistema utilize um código de referência para cada compra que é feita em sua loja, você pode utiliza-lo para vincular a uma transação no PagSeguro:

	$paymentRequest->setReference("I9635");

Você pode adicionar outros parâmetros ao objeto utilizando o método addParameter:

	$paymentRequest->addParameter('notificationURL', 'http://www.meusite.com.br/notificacao');
	$paymentRequest->addParameter('senderCPF', '12345678901');

Agora que você informou os dados da compra, você deve executar o método register, que faz a requisição à API de Pagamentos do PagSeguro, retornando a URL necessária para o comprador fazer o pagamento:

	
	// Informando as credenciais
	$credentials = new PagSeguroAccountCredentials(
		'suporte@lojamodelo.com.br', 
		'95112EE828D94278BD394E91C4388F20'
	);
	
	// fazendo a requisição a API do PagSeguro pra obter a URL de pagamento
	$url = $paymentRequest->register($credentials);
	

Com a URL em mãos você pode direcionar o comprador ao PagSeguro, para que ele faça o pagamento em ambiente seguro (HTTPS). Veja todas as opções da classe PagSeguroPaymentRequest na página de classes da biblioteca.

Obs.: o método register faz uma chamada via API, para isso é necessário informar as credenciais utilizando um objeto do tipo PagSeguroAccountCredentials. Se você deseja utilizar credenciais previamente definidas no arquivo de configurações, veja como utilizar o método getAccountCredentials da classe PagSeguroConfig.

Receber notificações

O PagSeguro pode enviar notificações ao seu sistema indicando a ocorrência de algum evento que requer sua atenção. Essas notificações são enviadas via POST para uma URL definida por você na página configuração da URL de notificação.

Cada notificação é formada por dois parâmetros: notificationType que representa o tipo de notificação e notificationCode que representa o código de notificação.

Por exemplo: quando há uma mudança no status de uma transação iniciada pelo seu sistema, o PagSeguro envia uma notificação com o parâmetro notificationType valorizado com a String 'transaction' e também o parâmetro notificationCode valorizado com o código de notificação.

Ao receber uma notificação indicando que há uma mudança no status de uma transação, você pode utilizar o método estático checkTransaction da classe PagSeguroNotificationService, passando o código da notificação como parâmetro da chamada. Esse método irá fazer uma consulta via API ao PagSeguro requisitando os dados da transação em questão, e retornará um objeto do tipo PagSeguroTransaction que representa a transação com todas as informações, inclusive seu status atualizado:

	/* Informando as credenciais  */  
	$credentials = new PagSeguroAccountCredentials(    
		'suporte@lojamodelo.com.br',     
		'95112EE828D94278BD394E91C4388F20'    
	);
	
	/* Tipo de notificação recebida */
	$type = $_POST['notificationType'];
	
	/* Código da notificação recebida */
	$code = $_POST['notificationCode'];
	
	
	/* Verificando tipo de notificação recebida */
	if ($type === 'transaction') {
		
		/* Obtendo o objeto PagSeguroTransaction a partir do código de notificação */
		$transaction = PagSeguroNotificationService::checkTransaction(
			$credentials,
			$code // código de notificação
		);
		
	}

Com o objeto PagSeguroTransaction você pode obter o status da transação utilizando o método getStatus que irá retornar um objeto do tipo PagSeguroTransactionStatus:

	/* objeto PagSeguroTransactionStatus */  
	$status = $transaction->getStatus();

Obs.: o método checkTransaction faz uma chamada via API, para isso é necessário informar as credenciais utilizando um objeto do tipo PagSeguroAccountCredentials. Se você deseja utilizar credenciais previamente definidas no arquivo de configurações, veja como utilizar o método getAccountCredentials da classe PagSeguroConfig.

Consultar transações por código

Sempre que precisar, você pode consultar dados de uma transação realizada em sua loja ou sistema através da API de consultas do PagSeguro.

Nesse contexto a classe PagSeguroTransactionSearchService lhe permite consultar uma transação a partir do código identificador. Utilize o método estático searchByCode para realizar a consulta, que irá retornar um objeto do tipo PagSeguroTransaction representando os dados da transação:

	/* Definindo as credenciais  */  
	$credentials = new PagSeguroAccountCredentials(    
		'suporte@lojamodelo.com.br',     
		'95112EE828D94278BD394E91C4388F20'    
	);
	
	/* Código identificador da transação  */  
	$transaction_id = '59A13D84-52DA-4AB8-B365-1E7D893052B0';
	
	/* 
		Realizando uma consulta de transação a partir do código identificador 
		para obter o objeto PagSeguroTransaction
	*/ 
	$transaction = PagSeguroTransactionSearchService::searchByCode(
		$credentials,
		$transaction_id
	);
	

Com o objeto PagSeguroTransaction você pode obter todos os dados da transação, por exemplo, o status através do método getStatus:

	/* Imprime o código do status da transação */
	echo $transaction->getStatus()->getValue();

Consultar transações por intervalo de datas

A classe PagSeguroTransactionSearchService possibilita consultar informações de transações que foram realizadas dentro um intervalo de datas.

Você informa o intervalo para o método estático searchByDate que retorna um objeto do tipo PagSeguroTransactionSearchResult contendo as transações consultadas.

	/* Definindo as credenciais  */  
	$credentials = new PagSeguroAccountCredentials(    
		'suporte@lojamodelo.com.br',     
		'95112EE828D94278BD394E91C4388F20'
	);
	
	/* Definindo a data de ínicio da consulta */
	$initialDate = '2011-06-01T08:50';
	
	/* Definindo a data de término da consulta */
	$finalDate   = '2011-06-29T10:30';
	
	/* Definindo o número máximo de resultados por página */
	$maxPageResults = 20;
	
	/* Definindo o número da página */
	$pageNumber = 1;
	
	/* Realizando a consulta */
	$result = PagSeguroTransactionSearchService::searchByDate(
		$credentials,		// credenciais
		$pageNumber, 		// número da página
		$maxPageResults,	// número máximo de resultados por página
		$initialDate,  		// data de ínicio
		$finalDate, 		// data de término
	);
	
	/* Obtendo as transações do objeto PagSeguroTransactionSearchResult */
	$transactions = $result->getTransactions();

Obs.: o método searchByDate faz uma chamada via API, para isso é necessário informar as credenciais utilizando um objeto do tipo PagSeguroAccountCredentials. Se você deseja utilizar credenciais previamente definidas no arquivo de configurações, veja como utilizar o método getAccountCredentials da classe PagSeguroConfig.

Configurações

A Biblioteca PagSeguro em PHP permite que você configure facilmente a maneira como deseja utiliza-la, centralizando as informações no arquivo de configuração PagSeguroConfig.php localizado no diretório config da biblioteca.

O arquivo de configurações contém o Array $PagSeguroConfig representando a lista de configurações da biblioteca. Cada índice desse Array representa um grupo de configurações, sendo que cada grupo é formado por conjuntos de pares chave/valor representando uma configuração específica.

A primeira configuração a ser feita é informar os dados de acesso da sua conta no PagSeguro. Esses dados de acesso são como credenciais para sua segurança, formadas por e-mail e token.

Veja abaixo como configurar as credenciais de uma conta no PagSeguro que possui o e-mail suporte@lojamodelo.com.br e o token 6BCBB0E0C2054CB486016E38A5E594F1:

	$PagSeguroConfig['credentials'] = Array();
	$PagSeguroConfig['credentials']['email'] = "suporte@lojamodelo.com.br";
	$PagSeguroConfig['credentials']['token'] = "95112EE828D94278BD394E91C4388F20";	

Ao definir uma configuração, é recomendável sobrescrever o Array $PagSeguroConfig de maneira manual, não utilizando valores dinâmicos.

Veja como funciona a classe PagSeguroConfig e como obter as credenciais definidas no arquivo de configurações.

Arquivo de log

A Biblioteca PagSeguro em PHP disponibiliza um arquivo de log que pode ser útil no processo de integração com as funcionalidades que a biblioteca oferece. Por padrão este log não é ativo. Para ativa-lo altere o arquivo de configurações, veja o exemplo abaixo:

	$PagSeguroConfig['log']['active'] = TRUE;

Ao utilizar a biblioteca com o log ativo, o arquivo é criado automaticamente. Você pode definir sua localização utilizando a configuração fileLocation. Informe o caminho completo no seu servidor, veja o exemplo abaixo:

	$PagSeguroConfig['log']['fileLocation'] = 'logs/log.txt';

Para o correto funcionamento é necessário que o diretório da localização do arquivo possua permissões de escrita.

Veja mais detalhes sobre o funcionamento do log da biblioteca utilizando a classe LogPagSeguro.

Obs.: se a configuração fileLocation não for definida, o arquivo de log será criado dentro da raiz do diretório da biblioteca com o nome PagSeguro.log.

Tratamento de exceções

A biblioteca PagSeguro em PHP pode lançar exceções do tipo PagSeguroServiceException, esse tipo de exceção é lançada nos momentos em que métodos que fazem chamadas via API são executados. Isso pode acontecer por alguma indisponibilidade no momento da conexão HTTP a uma API do PagSeguro, ou o PagSeguro verificou alguma inconsistência nos dados informados por você como p.e. omitir o token das suas credenciais.

Caso ocorra uma chamada via API com alguma informação inconsistente, o código de resposta da requisição HTTP não será do tipo (200 OK) e o conteúdo da resposta será uma lista com mensagens e códigos de erro. Os códigos de erro são úteis principalmente em tempo de desenvolvimento.

Como pode ser visto nos exemplos de uso da biblioteca no diretório examples, os métodos que fazem chamadas via API para o PagSeguro estão envolvidos por um bloco try/catch. Essa prática visa minimizar problemas, permitindo tratar a exceção e elaborar mensagens para seus usuários.

Com a classe PagSeguroServiceException você pode obter o código HTTP da conexão e a lista de erros (Array) retornada pelo PagSeguro em uma chamada via API.

O código abaixo exemplifica uma requisição via API para o PagSeguro, informando as credenciais sem informar o token. Isso irá lançar uma exceção do tipo PagSeguroServiceException resultando na execução do bloco catch. Veja como obter o código HTTP e as mensagens da lista de erros ao tratar essa exceção:

	/* Informando as credenciais (omitindo token) */
	$credentials = new PagSeguroAccountCredentials("suporte@lojamodelo.com.br", " "); 
	
	try {
		
		/*	
			Fazendo uma requisição via API com credenciais incorretas
		*/
		$url = $paymentRequest->register($credentials);
		
	} catch (PagSeguroServiceException $e) {
		
		echo $e->getHttpStatus(); // imprime o código HTTP
		
		foreach ($e->getErrors() as $key => $error) {
			echo $error->getCode(); // imprime o código do erro
			echo $error->getMessage(); // imprime a mensagem do erro
		}
		
	}

Obs: se você ativou o log da biblioteca, os erros de chamadas via API serão gravados automaticamente no arquivo de log.

A biblioteca PagSeguro em PHP pode também lançar exceções do tipo Exception. Comumente essa exceção é lançada quando alguma depedência não foi encontrada.

Por exemplo, se a biblioteca cURL utilizada para conectar servidores não for encontrada a exceção abaixo será lançada ao iniciar a biblioteca:

	Exception: cURL library is required.

Visando uma melhor experiência para os usuários de seu sistema, encorajamos fortemente o tratamento de exceções lançadas pela biblioteca PagSeguro em PHP.

Dependências

A biblioteca PagSeguro em PHP necessita das seguintes depências para seu funcionamento:

Standard PHP Library (SPL)

Biblioteca cURL

DOM extension

Tem alguma sugestão ou dúvida? desenvolvedores@pagseguro.com.br.