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 por exemplo 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 PaymentRequest 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:

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

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

Agora você deve adicionar os produtos ao objeto criado:

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:

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

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

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

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:

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:

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 PaymentRequest 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 tipoAccountCredentials. Se você deseja utilizar credenciais previamente definidas no arquivo de configurações, veja como utilizar o método getAccountCredentials da classe PagSeguroConfig.

Tem alguma dúvida sobre como integrar o PagSeguro? Entre em contato.

Antes de iniciar o fluxo de pagamentos, você pode utilizar o carrinho de compras do PagSeguro. Dessa maneira, você permite que o comprador altere o pedido ou mesmo retorne à sua loja para adicionar mais itens, antes de fechar o pedido e prosseguir com o pagamento. Com o carrinho de compras, os dados do pedido permanecerão na sessão do navegador. Essa solução é ideal para lojas mais simples, que não possuem tal funcionalidade.

O exemplo abaixo mostra um formulário HTML semelhante ao exemplo anterior, porém ilustrando o uso do carrinho de compras:

<!– Declaração do formulário –>
<form target=”pagseguro” method=”post”
action=”https://pagseguro.uol.com.br/v2/checkout/cart.html?action=add“>

<!– Campos obrigatórios –>
<input type=”hidden” name=”receiverEmail” value=”suporte@lojamodelo.com.br“>
<input type=”hidden” name=”currency” value=”BRL”>

<!– Itens do pagamento (ao menos um item é obrigatório) –>
<input type=”hidden” name=”itemId” value=”0001″>
<input type=”hidden” name=”itemDescription” value=”Notebook Prata”>
<input type=”hidden” name=”itemAmount” value=”2430.00″>
<input type=”hidden” name=”itemQuantity” value=”1″>
<input type=”hidden” name=”itemWeight” value=”1000″>

<!– Código de referência do pagamento no seu sistema (opcional) –>
<input type=”hidden” name=”reference” value=”REF1234″>

<!– submit do form (obrigatório) –>
<input type=”image” name=”submit”
src=”https://p.simg.uol.com.br/out/pagseguro/i/botoes/pagamentos/120×53-pagar.gif“
alt=”Pague com PagSeguro”>

</form>

Observe que as informações de frete e os dados do comprador não são necessários. Além disso, você deve informar o endereço da página de carrinho de compras no PagSeguro, adicionando um novo item ao carrinho:

https://pagseguro.uol.com.br/v2/checkout/cart.html?action=add

Ver Carrinho

Você também poderá inserir uma opção “Ver carrinho” na sua loja. Assim, o comprador irá ver os itens que já foram adicionados ao pedido. Copie e cole o código em seu site. Escolha um lugar em sua página onde o comprador o encontre facilmente.

<a  href=”https://pagseguro.uol.com.br/v2/checkout/cart.html?action=view“>
<img src=”https://p.simg.uol.com.br/out/pagseguro/i/botoes/pagamentos/99×61-carrinho-assina.gif” alt=”Ver carrinho”/>
</a>

Se você preferir, utilize as seguintes imagens dos botões criadas pelo PagSeguro:

Tem alguma dúvida sobre como integrar o PagSeguro? Entre em contato.

O que é?

Um dos erros mais comuns que alguns desenvolvedores tem ao integrar o PagSeguro é na validação das informações recebidas no Retorno Automático.

Isso normalmente ocorre quando há uma divergência na codificação de caracteres (encoding, charset) do sistema se comparada à utilizada pelo PagSeguro, no caso ISO-8859-1. Ou seja, é como se o sistema utilizado estivesse preparado para tratar as informações apenas em UTF – 8 e ao receber dados contendo uma codificação diferente, os caracteres aparecem “quebrados”, o que impede a interpretação correta dessas informações.

Veja o exemplo abaixo:

Como a palavra “Cartão de Crédito” possui caracteres especiais, no caso acentos, a informação referente a essa transação não foi validada devido ao erro de encoding.

Como corrigir?

Para corrigir o erro de acentuação, o sistema deverá trabalhar utilizando a mesma codificação utilizada pelo PagSeguro  (ISO-8859-1) ou converter os dados antes da manipulação dessas informações.

Uma forma simples de evitar erros de validação é utilizando a API de Notificações, pois o código enviado para o seu sistema não possui acentuação, o que facilita a integração, gerando mais segurança.

A API de Notificação funciona de forma parecida com o Retorno Automático de Dados, porém a etapa de verificação é realizada por um código que não possui acentuação, evitando o problema acima, além de possuir mais campos referentes à transação. Com isso você terá informações mais detalhadas e precisas sobre a venda de seus produtos.

Veja documentação sobre a API de Notificação.

Com as bibliotecas do PagSeguro, fica muito mais fácil integrar em seu site. Essas bibliotecas estão de acordo com a versão mais atualizada do Guia de Integração do PagSeguro (Versão 2).

Em todas as bibliotecas você encontrará:

- Classes de domínios que representam pagamentos, notificações e transações;

- Criação de checkouts via API;

- Controller para processar notificações de pagamento enviadas pelo PagSeguro;

- Módulo de consulta de transações.

•  Biblioteca PagSeguro em PHP.

• Biblioteca PagSeguro em Java.           

• Biblioteca PagSeguro em .NET.

Tem alguma sugestão ou viu algum erro em nosso Guia? Entre em contato conosco.

Aprenda como utilizar as ferramentas que o PagSeguro oferece para integrar seu sistema da forma mais adequada às suas necessidades.

INTEGRAÇÃO BÁSICA

Você pode integrar o PagSeguro ao seu site mesmo sem ter conhecimentos avançados de programação. Veja como é simples:

 1-    Insira Botões de Pagamento em seu site.

2-    Acompanhe as notificações por e-mail.

3-    Consulte suas transações no extrato de transações.

INTEGRAÇÃO COMPLETA

E para ter acesso a todas as funcionalidades e ter todo o potencial do PagSeguro, veja as nossas tecnologias mais avançadas de integração:

1-    Utilize a API de Pagamentos e configure o redirecionamento no final do fluxo de pagamento.

2-    Acompanhe as notificações usando a API de Notificações.

3-    Consulte seu histórico de transações ou detalhes de uma transação individual.

Obs.: o sistema de versionamento das APIs do PagSeguro foi criado de forma a viabilizar a evolução dos serviços e garantir a compatibilidade com os clientes já integrados. Saiba mais sobre o sistema de versionamento das APIs.

Com o PagSeguro, você pode trabalhar com três tipos de frete: por valor fixo, por peso ou frete adicional com valor fixo.

Você também pode disponibilizar para seus clientes a ferramenta de cálculo de frete, para que saiba exatamente o quanto pagará pelo envio da mercadoria.

Para utilizar um desses tipos de frete, você precisa configurá-lo na página de Frete no Menu Preferências em sua conta.

Além disso, é possível disponibilizar também a forma de envio em sua loja. Seus produtos podem ser enviados apenas por SEDEX ou Encomenda normal (PAC), ou se preferir, você pode utilizar as duas formas de envio e deixar a escolha por parte do comprador.

Frete fixo:

Utilize-o para cobrar sempre o valor de frete especificado. Para mais de um item, o valor fixo do frete será multiplicado pelo número de itens. Esta opção não oferece desconto caso o cliente compre mais de um item.

Frete por peso:

Utilize-o para cobrar o frete de acordo com o peso do produto, com base na tabela dos Correios e no CEP informado pelo cliente. Seu cliente poderá optar por Encomenda econômica (PAC) ou Sedex. O limite estabelecido pelos Correios é de até 30kg ou R$10.000,00.

Atenção: Se o somatório dos pesos dos itens ultrapassar o limite de 30Kg, ou se o valor total ultrapassar R$10.000,00, o frete não será calculado no PagSeguro, e deverá ser cobrado à parte, diretamente com seu cliente.

Frete adicional com valor fixo:

Cobrar o frete do item que tiver o valor mais alto no carrinho e cobrar um valor adicional fixo para cada item extra. Não será cobrado frete algum para itens que tenham frete grátis (nem mesmo o valor extra). Esta opção oferece ao cliente desconto no frete dos itens adicionais.

Obs: Os valores de frete por peso calculados pelo PagSeguro são apenas uma estimativa obtida junto aos Correios e devem ser confirmados no ato da postagem.

Saiba como integrar o frete em sua loja virtual, acesse: http://zip.net/bxcgs5

Com a nova API do PagSeguro, é possível direcionar o comprador para uma URL Dinâmica ou para uma URL Fixa. Isso possibilita que o vendedor informe o usuário sobre a transação ou apenas apresentar uma tela de agradecimento pela compra.

Entenda a diferença entre elas:

Redirecionando o comprador para uma URL fixa

Nesta URL, você poderá preparar uma mensagem ao seu comprador, com explicações sobre aprovação do pagamento e sobre a liberação do produto. Essa mensagem será bastante útil para evitar dúvidas dos compradores sobre o processo de compra.

Por exemplo, configurando a URL abaixo no PagSeguro, é possível exibir uma mensagem padrão para todos os compradores que terminarem o fluxo de pagamento:

https://pagseguro.uol.com.br/lojamodelo/return.html

Para ativar essa função, configure um endereço fixo na área de configurações do PagSeguro.

Redirecionando o comprador para uma URL dinâmica

Você pode informar uma URL de redirecionamento diferente para cada pagamento realizado. Esta opção possui grande flexibilidade, pois permite que você mostre uma página específica para cada pagamento.

Para utilizar essa funcionalidade você deve configurar sua conta para aceitar somente requisições de pagamentos gerados via API.

Ao gerar uma requisição utilizando a API de Pagamentos, especifique a URL de redirecionamento no parâmetro redirectURL.

Por exemplo:

<redirectURL> https://pagseguro.uol.com.br/lojamodelo/notebook-prata-return.html </redirectURL>

A vantagem de uma URL dinâmica é que você terá muito mais flexibilidade para definir para onde o usuário deverá retornar ao final do fluxo. Poderá criar, por exemplo, páginas específicas para promoções ou para um determinado produto ou serviço ofertado em sua loja. Fique ligado para mais dicas do PagSeguro para desenvolvedores!

“Transação inválida. Sempre inicie transações a partir de sites confiáveis”.

Algumas vezes, ao implantar o sistema do PagSeguro para realizar suas vendas, aparece a seguinte mensagem:

Por que isso ocorre?

No dia 3 de agosto o PagSeguro lançou as famosas APIs, para auxiliar na integração.

Uma delas é a de pagamento, cuja finalidade é fazer uma integração mais dinâmica e segura. Ao utilizar essa nova API de pagamento, automaticamente seu sistema se programa para aceitar pagamentos somente por ela. É necessário desabilitar essa opção para sanar o problema. Veja abaixo como:

1 – Acesse sua conta do PagSeguro – https://pagseguro.uol.com.br/

Acesse no menu a opção “Integrações”.

Escolha “Pagamentos via API”

Desmarque a opção “Quero receber somente pagamentos via API”.

Será exibida uma caixa de diálogo com a seguinte pergunta: “Deseja desativar a restrição de pagamentos com API?”

Seguindo todos os passos corretamente, será exibida a tela abaixo:

Agora você poderá receber seus pagamentos normalmente, eliminando os possíveis conflitos. Caso tenha alguma dúvida, entre em contato com nossa equipe de desenvolvedores, pelo e-mail desenvolvedores@pagseguro.com.br.

O PagSeguro tem uma novidade muito boa para você desenvolvedor. São as novas APIs de integração do PagSeguro. São três serviços: pagamentos, notificações e consultas. São aplicações que visam oferecer mais flexibilidade aos desenvolvedores e mais segurança aos vendedores. Leia mais…;

Uma ferramenta como o PagSeguro só faz sentido quando os desenvolvedores podem usar e abusar das suas possibilidades. Por isso mesmo a gente cuida muito bem de cada um de vocês. No Guia do Desenvolvedor você encontra cada detalhe necessário para o desenvolvimento de sites de comércio eletrônico integrados ao nosso sistema – criação de carrinho próprio, retorno automático, cálculo de frete e criação de botões de doação. Mantemos, com o iMasters, um Fórum exclusivo para solucionar questões que aparecem naturalmente no desenvolvimento.

Para manter o jogo no campo do ganha-ganha, o PagSeguro também tem o Bônus por Indicação, um programa em que remuneramos os cadastros gerados através de botões específicos.

E agora, para atender diretamente às suas questões, entre em contato através do e-mail desenvolvedores@pagseguro.com.br. O comunicador funciona de segunda a sexta, das 9h às 18h, apenas para dúvidas técnicas.