Retorno Automático
Após o processo de compra e pagamento, o usuário é enviado de volta a seu site. Para isso, você deve configurar uma URL de retorno.
Antes de enviar o usuário para essa URL, o robô do PagSeguro faz um POST para ela, em segundo plano, com os dados e status da transação. Lendo esse POST, você pode obter o status do pedido. Se o pagamento entrou em análise, ou se o usuário pagou usando boleto bancário, o status será “Aguardando Pagamento” ou “Em Análise”. Nesses casos, quando a transação for confirmada (o que pode acontecer alguns dias depois) a loja receberá outro POST, informando o novo status. Cada vez que a transação muda de status, um POST é enviado.
Veja como funciona:
1. Comprador é direcionado para o PagSeguro e faz seu pagamento.
Isso pode ser feito usando o carrinho PagSeguro ou carrinho próprio, não faz diferença. Após exibir o boleto, ou concluir o pagamento, o usuário vê uma tela como essa (clique para ampliar):
2. O PagSeguro faz um POST em segundo plano para a loja
O robô do PagSeguro envia os dados da compra e o status da transação para a loja.
ATENÇÂO: Este envio é feito em segundo plano pelo robô do PagSeguro. Não é o navegador do comprador que faz esse POST. Logo, você não poderá usar variáveis de sessão (pois não há sessão) nem imprimir nada na tela (com echo, print, Response.Write, etc.) pois só o Robô do PagSeguro vai ver o que você imprimir neste momento.
Outro detalhe importante é o fato de que esse POST é enviado para a mesma URL de retorno para a qual o comprador vai ser em seguida redirecionado. Assim, para saber se é o comprador ou o robô do PagSeguro que está acessando a página, você precisa verificar se há dados no POST.
Os dados que seu site receberá são:
| Campos enviados ao seu site | ||
| Nome | Descrição | |
|---|---|---|
| VendedorEmail | Seu email | |
| TransacaoID | Identificação da Transação | |
| Referencia | Código de referência gerado por você e enviado ao PagSeguro para identificação em seu site. | |
| TipoFrete | Tipo de frete pago pelo cliente. Pode receber as seguintes variáveis:
FR – Frete fixo definido por você |
|
| ValorFrete | Valor total do frete pago pelo cliente.
Formato:
|
|
| Anotacao | Anotação enviada pelo cliente | |
| DataTransacao | Data e hora da transação.
Formatos:
|
|
| TipoPagamento | Tipo de pagamento efetuado pelo cliente. Pode receber as seguintes variáveis:
Obs.: No caso de doação, o tipo de pagamento será um dos informados acima, e um produto com o nome Doação será enviado neste formulário. |
|
| StatusTransacao | Status da transação efetuada. Pode receber as seguintes variáveis:
|
|
| CliNome | Nome do cliente | |
| CliEmail | Email do cliente | |
| CliEndereco | Endereço do cliente | |
| CliNumero | Número da residência do cliente | |
| CliComplemento | Complemento do endereço do cliente | |
| CliBairro | Bairro do cliente | |
| CliCidade | Cidade do cliente | |
| CliEstado | Estado do cliente | |
| CliCEP | CEP do cliente Formato: 00000000 |
|
| CliTelefone | Telefone do cliente Formato: 00 00000000 |
|
| ProdID_x | ID do produto | |
| ProdDescricao_x | Descrição do produto | |
| ProdValor_x | Valor unitário do produto | |
| ProdQuantidade_x | Quantidade comprada do produto | |
| ProdFrete_x | Valor do frete deste produto Formato: 0,00 |
|
| ProdExtras_x | Valor de taxas estras deste produto Formato: 0,00 |
|
| NumItens | Quantidade de itens recebidos. | |
3. Você verifica a transação junto ao PagSeguro.
Imagine que um invasor descubra sua URL de retorno, o que não é difícil, uma vez que é a mesma para a qual ele será enviado ao final da transação. Ele poderia construir um POST igual ao do PagSeguro para liberar seus pedidos sem tê-los pago. Por isso, cada vez que sua URL de retorno receber um POST, você precisa verificá-lo junto ao PagSeguro.
Para isso, você vai precisar de um código especial gerado pelo PagSeguro, o Token. Ao receber o POST, você deve enviar os dados de volta para o PagSeguro, incluindo dois novos dados:
| Nome | valor |
|---|---|
| Comando | validar |
| Token | seu Token |
A URL para onde você vai enviar esse post é:
https://pagseguro.uol.com.br/Security/NPI/Default.aspx/Se o status da transação estiver correto, o PagSeguro vai retornar para esse POST a string “VERIFICADO”. Assim, se um invasor tentar construir um POST semelhante, sua loja poderá ignorá-lo, uma vez que ele não será verificado pelo PagSeguro.
4. O usuário é redirecionado para a URL de retorno
Ao final do processo, o usuário é enviado para a URL de retorno cadastrada:
Esse é um redirecionamento comum, não é enviado nenhum dado sobre a transação nesse momento. Se tudo correu bem, você já capturou os dados da transação no POST em segundo plano e o id do pedido ainda está na sessão do comprador, de modo que você pode mostrar a ele o status do pedido. Caso ocorra algum imprevisto, como a perda da sessão, não há problema, você pode mostrar a ele ainda assim uma mensagem informando que o pedido foi recebido e assim que o pagamento for confirmado, será processado.
Muitos desenvolvedores preferem, neste passo, simplesmente exibir essa mensagem, quer o retorno já tenha sido capturado ou não.