Como funciona o retorno do pagSeguro e do Pagamento Digital?

Esse é o primeiro artigo da série de posts que eu pretendo fazer sobre os meios de pagamento pagSeguro e Pagamento Digital.
Então, vamos começar pela parte mais complexa: o tão temido retorno automático (música de terror).
Depois de dias lutando, perguntando ao suporte, pesquisando, recebendo respostas inconclusivas e testando... Aqui vai:
O FAQ definitivo para quem pretende entender como funciona o retorno do pagSeguro e Pagamento Digital.

* Post direcionado principalmente para programadores.

1. Ele só me envia os dados da transação se o cliente esperar os segundos necessários para o redirecionamento ou clicar no botão 'Retornar à loja'?
Não. Ambos trabalham com o que se chama (NPI - Notificação de Pagamento Instantânea). Ou seja, independente de o cliente clicar no botão, um POST com os dados da transação feita por ele será enviado a você.

2. Quanto tempo leva isso?
Segundo o suporte do pagSeguro - 15 segundos;
Segundo o suporte do Pagamento Digital - 5 minutos;
Pelos meus testes: é realmente isso.

Ou seja, além desses tempos em que o POST é enviado por background (sem que o cliente perceba), um outro tempo (de 20 segundos aproximadamente) é contado até que o cliente seja redirecionado à página de retorno sem POST algum.
Apenas para receber a feliz mensagem de que a transação foi finalizada.

3. E, se eu tiver um carrinho de compras gravado em SESSION ou COOKIE, eu posso mandar esvaziar o carrinho nessa página do retorno?
Poder, você pode, mas ele só será esvaziado se o cliente clicar no botão de retorno à loja ou esperar os segundos de redirecionamento automático (20 segundos aproximadamente). Se ele fechar a página antes disso, o carrinho continuará cheio. Ou seja, nada bom né? Pois você não pode confiar que o cliente fará isso.

4. Por quê isso?
Porque a SESSION/COOKIE do carrinho de compras está salva no computador do cliente e a página de retorno (quando não acessada diretamente pelo cliente) é chamada pelo computador do pagSeguro ou Pagamento Digital. Ou seja: o carrinho não está salvo lá, não tem como ele limpar uma SESSION/COOKIE que não existe.

5. Um, então eu devo salvar a transação antes de ir para o ambiente de pagamento (do pagseguro ou Pagamento Digital)?
Essa não é uma boa prática. Porque?
- Você pode encher seu banco de dados com transações que o cliente não finalizou (ex: o cliente vai até a página de pagamento e desiste).
- Você está reduzindo seu estoque sem que realmente o cliente tenha comprado a mercadoria.
- Você terá que checar manualmente se o cliente terminou a compra nos sites do pagSeguro e Pagamento Digital.

6. E, como eu posso evitar isso?
Simples:
- Monte os formulários que enviam os dados para o pagSeguro e pagamento digital e no onsubmit() peça que além de seguir para o ambiente de pagamento deles, o carrinho seja esvaziado.

7. Um, ok, mas quantas vezes eu recebo um POST com dados do pagSeguro e do Pagamento Digital?
Aqui está o que MUITA GENTE não sabe, porque o suporte não explica corretamente:
Sempre que o status da transação for alterado, você recebe um POST.
Ex:
- Você recebe um POST assim que a transação é efetuada.
- Outro, dois dias depois, mais ou menos, assim que a transação é a aprovada.
- Outro, quando a transação é compensada... e assim vai.

8. Um, então o retorno não funciona apenas no final da compra?
Não. :] Ele realmente funciona pra algo além disso, como te avisar quando o pagamento foi aprovado e você pode enviar a mercadoria.

9. Mas, tipo, se eles me enviam um POST várias vezes como eu vou saber qual comando executar?
É crucial que VOCÊ faça essa verificação no seu código. Ou seja, para saber se a transação deve ser inserida no banco ou apenas ter o seu status modificado, você deve, primeiro, verificar se a transação existe, se existir apenas modifique-a, senão, adicione-a.

10. E aquelas verificações de segurança, em que tenho que usar o meu token para reenviar os dados para o pagSeguro e Pagamento Digital?
Sim, é necessário. Ao menos para o Pagamento Digital é obrigatório e é super recomendado que você realmente o faça.

11. Mas voltando, se eu deletei o meu carrinho de compras como eu vou salvar os dados dos produtos da transação?
Tanto pagSeguro como Pagamento Digital enviam os produtos salvos, é só você dar um um loop neles.

12. E o valor total, pagseguro?
Pois é, na documentação do pagseguro nenhum valor total é enviado a loja. Você mesmo vai ter que fazer os cálculos, somando dentro do loop o valor * quantidade do produto ao valor total.

13. Um, qual a melhor forma de fazer testes com o retorno?
FAÇA UM LOG DE AÇÕES. Isso é vital, sério! A cada etapa ultrapassada, você salva a ação no log.
Ex: 1. POST recebido, 2. POST vazio, 3. POST cheio sendo verificado, 4. POST verificado, 5. Transação do POST já existe, atualiza, 6. Transação do POST não existe, insere...

Assim, quando a ação não for salva no log, você saberá o que deu errado.

E, para realizar transações e não pagar, use o Boleto Bancário e um e-mail diferente do cadastrado para a sua loja.

É isso. :)