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.5.0

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:

<script type="text/javascript"
  src="https://stc.pagseguro.uol.com.br/pagseguro/api/v2/checkout/pagseguro.directpayment.js">
</script>

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.

<script type="text/javascript">
  PagSeguroDirectPayment.setSessionId('sessionId');
</script>

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

<script type="text/javascript">
  PagSeguroDirectPayment.getSenderHash();
</script>
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.

<script type="text/javascript">
  PagSeguroDirectPayment.getPaymentMethods({
    success: {função de callback para chamadas bem sucedidas},
    error: {função de callback para chamadas que falharam},
    complete: {função de callback para todas chamadas}
  });
</script>

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).

<script type="text/javascript"
  PagSeguroDirectPayment.getBrand({
    cardBin: $("input#cartao").val(),
    success: {função de callback para chamadas bem sucedidas},
    error: {função de callback para chamadas que falharam},
    complete: {função de callback para todas chamadas}
  });
</script>

Ainda seguindo o cenário de pagamento utilizando cartão de crédito é necessário obter o token para o cartão utilizado neste pagamento, para isto utilizaremos o método createCardToken (disponível no JavaScript importado).

<script type="text/javascript"
  var param = {
    cardNumber: $("input#cartao").val(),
    brand: $("input#bandeira").val();
    cvv: $("input#cvv").val(),
    expirationMonth: $("input#validadeMes").val(),
    expirationYear: $("input#validadeAno").val(),
    success: {função de callback para chamadas bem sucedidas},
    error: {função de callback para chamadas que falharam},
    complete: {função de callback para todas chamadas}
  }

  PagSeguroDirectPayment.createCardToken(param);
</script>

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).

<script type="text/javascript"
  PagSeguroDirectPayment.getInstallments({
    amount: $("input#valorPgto").val(),
    brand: $("input#bandeira").val(),
    maxInstallmentNoInterest: 2,
    success: {função de callback para chamadas bem sucedidas},
    error: {função de callback para chamadas que falharam},
    complete: {função de callback para todas chamadas}
  });
</script>
Mais informações sobre o retorno dos métodos disponíveis no JavaScript podem ser encontradas em um PDF com a documentação completa.

Agora que você já possui todas as informações necessárias, poderá executar a chamada API (com a lib PagSeguro PHP) informando os dados de pagamento, para fazer isso comece instanciando a classe PagSeguroDirectPaymentRequest.

Definindo o modo e método de pagamento.

  $directPaymentRequest = new PagSeguroDirectPaymentRequest();
  $directpaymentRequest->setPaymentMode('DEFAULT'); // GATEWAY
  $directpaymentRequest->setPaymentMethod('CREDIT_CARD');

Definindo a moeda a ser utilizada no pagamento.

  $directpaymentRequest->setCurrency("BRL");

Adicionando produtos/serviços na solicitação.

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

Informando os dados do comprador.

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

  $directpaymentRequest->setSenderHash(
    'd94d002b6998ca9cd69092746518e50aded5a54aef64c4877ccea02573694987'
  );

Informando o endereço de entrega, assim como tipo do frete.

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

Informando os dados do cartão.

  $creditCardToken = "1a45e0f9029344898d1b1fe00d90a66b";

  $installments = new PagSeguroInstallment(
    array(
      'quantity' => '1',
      'value' => '2580.99'
    )
  );

  $billingAddress = new PagSeguroBilling(
      array(
        'postalCode' => '01452002',
        'street' => 'Av. Brig. Faria Lima',
        'number' => '1384',
        'complement' => 'apto. 114',
        'district' => 'Jardim Paulistano',
        'city' => 'São Paulo',
        'state' => 'SP',
        'country' => 'BRA'
      )
  );

  $creditCardData = new PagSeguroCreditCardCheckout(
    array(
      'token' => $creditCardToken,
      'installment' => $installments,
      'billing' => $billingAddress,
      'holder' => new PagSeguroCreditCardHolder(
        array(
          'name' => 'João Comprador',
          'birthDate' => date('01/10/1979'),
          'areaCode' => '11',
          'number' => '56273440',
          'documents' => array(
            'type' => 'CPF',
            'value' => '156.009.442-76'
          )
        )
      )
    )
  );

  $directpaymentRequest->setCreditCard($creditCardData);

Por fim você deve fazer a requisição no sistema do PagSeguro. O retorno do método register, por padrão, será um objeto com a resposta da requisição.

  try {

    $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
    $response = $directpaymentRequest->register($credentials);

  } catch (PagSeguroServiceException $e) {
      die($e->getMessage());
  }
Outras formas de integração com Checkout Transparente podem ser encontrados no diretório ../source/examples

Consultas

  • Por código de notificação

    O PagSeguro pode enviar notificações ao seu sistema (POST) indicando a ocorrência de algum evento que requer sua atenção. Para mais informações sobre o recebimento de notificações clique aqui.

                try {
    
                  $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
                  $response = PagSeguroNotificationService::checkTransaction(
                    $credentials,
                    $notificationCode
                  );
    
                } catch (PagSeguroServiceException $e) {
                  die($e->getMessage());
                }
            
  • Por código da transação

    Sempre que precisar, você pode consultar dados de uma transação específica utilizando seu código identificador.

                try {
    
                  $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
                  $response = PagSeguroTransactionSearchService::searchByCode(
                    $credentials,
                    $transactionCode
                  );
    
                } catch (PagSeguroServiceException $e) {
                  die($e->getMessage());
                }
            
  • Por código de referência

    Você pode buscar transações com base em um código de referência.

                try {
    
                  $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
                  $response = PagSeguroTransactionSearchService::searchByReference(
                    $credentials,
                    $reference,
                    $initialDate,
                    $finalDate,
                    $pageNumber,
                    $maxPageResults
                  );
    
                } catch (PagSeguroServiceException $e) {
                  die($e->getMessage());
                }
            
  • Transações concluídas - por intervalo de datas

    Para facilitar seu controle financeiro e seu estoque, você pode solicitar uma lista com histórico das transações da sua loja.

                try {
    
                  $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()
                  $response = PagSeguroTransactionSearchService::searchByDate(
                    $credentials,
                    $pageNumber,
                    $maxPageResults,
                    $initialDate,
                    $finalDate
                  );
    
                } catch (PagSeguroServiceException $e) {
                  die($e->getMessage());
                }
            
  • Transações abandonadas - por intervalo de datas

    A consulta destas transações é útil para que você identifique quais transações não foram concluídas devido ao abandono do fluxo de pagamento e tente fazer algum processo de recuperação junto ao comprador.

                try {
    
                  $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials();
                  $response = PagSeguroTransactionSearchService::searchAbandoned(
                    $credentials,
                    $pageNumber,
                    $maxPageResults,
                    $initialDate,
                    $finalDate
                  );
    
                } catch (PagSeguroServiceException $e) {
                  die($e->getMessage());
                }
            

Estorno

Sempre que precisar você pode solicitar o estorno parcial ou total de uma transação previamente paga. A chamada ao serviço pode ser feita da seguinte forma:

        $transactionCode = "6337FB5F-6B4C-432A-BDF4-FCE950CCCA64";

        $refundAmount = "1000.00"; // opcional

        try {

            $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()

            $response = PagSeguroRefundService::createRefundRequest(
              $credentials,
              $transactionCode,
              $refundAmount
            );

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

Cancelamento

Sempre que precisar você pode solicitar o cancelamento de uma transação que ainda esteja sendo processada. A chamada ao serviço pode ser feita da seguinte forma:

        $transactionCode = "7737FC3F-6B4C-435B-BDF4-FEB950CCAA88";

        try {

            $credentials = PagSeguroConfig::getAccountCredentials(); // getApplicationCredentials()

            $response = PagSeguroCancelService::createRequest($credentials, $transactionCode);

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

Licença

Copyright 2014 PagSeguro Internet LTDA.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Notas

O PagSeguro somente aceita pagamento utilizando a moeda Real brasileiro (BRL).

Certifique-se que o email e o token informados estejam relacionados a uma conta que possua o perfil de vendedor ou empresarial.

Certifique-se que tenha definido corretamente o charset de acordo com a codificação (ISO-8859-1 ou UTF-8) do seu sistema. Isso irá prevenir que as transações gerem possíveis erros ou quebras ou ainda que caracteres especiais possam ser apresentados de maneira diferente do habitual.

Nem todos os serviços descritos aqui estão disponíveis comercialmente para todos os clientes. Para mais informações acesse nosso fórum e consulte a disponibilidade do serviço para sua conta.

Dúvidas de como integrar com o PagSeguro? Participe das discussões e tire suas dúvidas no Fórum PagSeguro.