Definir como página inicial
Faça do UOL sua home page
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.7.1

Baixar agora

Instalação

  1. Baixe o repositório como arquivo zip ou faça um fork
  2. Dentro do diretório source existem dois principais 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.

Alternativamente, é possível utilizar o Composer para carregar a biblioteca (pagseguro/php).

Configuração

Para fazer uso real da biblioteca, é preciso fazer algumas configurações no arquivo PagSeguroConfig.php, que encontra-se no diretório 'config'. As opções disponíveis estão descritas abaixo.

environment: aceita os valores production e sandbox.
email: e-mail cadastrado.
token production: token gerado no PagSeguro.
token sandbox: token gerado no Sandbox.
appId production: ID da aplicação criada no PagSeguro.
appKey production: Chave da aplicação criada no PagSeguro.
appId sandbox: ID da aplicação criada no Sandbox.
appKey sandbox: Chave da aplicação criada no Sandbox.
charset: codificação do seu sistema (ISO-8859-1 ou UTF-8).
log: ativa/desativa a geração de logs.
fileLocation: local onde o arquivo de log será gravado. Ex.: ../PagSeguroLibrary/logs.txt

Requisição de Checkout

Para iniciar uma requisição de checkout, você precisa instanciar a classe PagSeguroPaymentRequest. Em seguida você deve informar os dados da requisição, como produtos/serviços, endereço do comprador, enfim.

Adicionando itens na requisição de pagamento.

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

Informando o endereço do comprador, assim como tipo do frete.

  $sedexCode = PagSeguroShippingType::getCodeByType('SEDEX');
  $paymentRequest->setShippingType($sedexCode);
  $paymentRequest->setShippingAddress(
    '01452002',
    'Av. Brig. Faria Lima',
    '1384',
    'apto. 114',
    'Jardim Paulistano',
    'São Paulo',
    'SP',
    'BRA'
  );

Caso você já tenha os dados do comprador, poderá informá-los para facilitar o fluxo de pagamento. Desta forma ele não precisará informá-los novamente.

  $paymentRequest->setSender(
    'João Comprador',
    'email@comprador.com.br',
    '11',
    '56273440',
    'CPF',
    '156.009.442-76'
  );

Definindo a moeda a ser utilizada no pagamento.

  $paymentRequest->setCurrency("BRL");

Definindo informações adicionais, que poderão ser utilizadas pelo seu sistema após o fluxo de pagamento no PagSeguro.

  // Referenciando a transação do PagSeguro em seu sistema
  $paymentRequest->setReference("REF123");

  // URL para onde o comprador será redirecionado (GET) após o fluxo de pagamento
  $paymentRequest->setRedirectUrl("http://www.lojamodelo.com.br");

  // URL para onde serão enviadas notificações (POST) indicando alterações no status da transação
  $paymentRequest->addParameter('notificationURL', 'http://www.lojamodelo.com.br/nas');

Você pode definir percentuais de descontos a serem oferecidos com base no meio de pagamento escolhido pelo seu cliente, durante o checkout, no ambiente do PagSeguro.

  $paymentRequest->addPaymentMethodConfig('CREDIT_CARD', 1.00, 'DISCOUNT_PERCENT');
  $paymentRequest->addPaymentMethodConfig('EFT', 2.90, 'DISCOUNT_PERCENT');
  $paymentRequest->addPaymentMethodConfig('BOLETO', 10.00, 'DISCOUNT_PERCENT');
  $paymentRequest->addPaymentMethodConfig('DEPOSIT', 3.45, 'DISCOUNT_PERCENT');
  $paymentRequest->addPaymentMethodConfig('BALANCE', 0.01, 'DISCOUNT_PERCENT');

É possível adicionar na requisição de checkout parâmetros/informações que, apesar de já terem sido implementados na API, ainda não estão disponíveis em forma de métodos na biblioteca.

  $paymentRequest->addParameter('senderBornDate', '07/05/1981');

Por fim você deve registrar a requisição no sistema do PagSeguro. O retorno do método register, por padrão, será a URL que deverá ser utilizada para redirecionar o comprador para a tela de pagamento no PagSeguro.

A maneira de realizar o redirecionamento do comprador para efetivar o pagamento no PagSeguro após o retorno da chamada ao método register depende da implementação de seu sistema.

  try {

    $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
    $checkoutUrl = $paymentRequest->register($credentials);

  } catch (PagSeguroServiceException $e) {
      die($e->getMessage());
  }

Requisição de Checkout Transparente

A integração com Checkout Transparente utiliza, além de classes e métodos disponibilizados na lib PagSeguro PHP, funções JavaScript para algumas operações que devem ser executadas no browser do cliente.

O primeiro passo desta integração consiste em iniciar uma sessão de pagamento, utilizando o método getSession disponível na lib PagSeguro PHP.

  try {

    $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
    $sessionId = PagSeguroSessionService::getSession($credentials);

  } catch (PagSeguroServiceException $e) {
    die($e->getMessage());
  }

Em seguida é preciso setar o id da sessão. Para isso você precisa importar em sua página de pagamento o seguinte JavaScript:


Esse JavaScript possui um objeto chamado PagSeguroDirectPayment, que é a interface de acesso aos métodos. Após a importação do arquivo, execute o método setSessionId (disponível no JavaScript importado), com o ID de sessão gerado anteriormente.


Você precisará obter um identificador para o comprador, utilizando o método getSenderHash (disponível no JavaScript importado).


Este método possui algumas dependências e, por isso, recomendamos que o getSenderHash não seja executado no onLoad da página. Você pode executá-lo, por exemplo, quando o cliente clicar no botão de conclusão de pagamento.

Para descobrir os meios de pagamento disponíveis você pode utilizar o método getPaymentMethods (disponível no JavaScript importado), que retornará um JSON contendo informações como o nome utilizado na chamada, nome de exibição, status (se está disponível no momento) e também o caminho para as imagens do meio de pagamento.


No caso de pagamentos com cartão de crédito é possível determinar a bandeira do cartão que está sendo utilizado pelo comprador através do método getBrand (disponível no JavaScript importado), bastando informar o BIN do cartão (seis primeiros dígitos).


Para finalizar esta parte do fluxo de integração, é preciso obter as opções de parcelamento para o cartão escolhido utilizando o método getInstallments (disponível no JavaScript importado).