URL de callback ou URL de retorno: porque o cliente voltar ao site não prova o pagamento

PHP e Programação·· 2 visualizações· 4 min de leitura

A resposta curta: num pagamento online há, normalmente, dois endereços seus que o operador usa. O URL de retorno (return URL, success URL) é para onde o navegador do cliente é mandado depois de pagar: serve para lhe mostrar uma página. O URL de callback (também chamado notify URL, IPN ou webhook) é chamado pelo servidor do operador directamente ao seu: é esse que confirma o pagamento. Quem marca encomendas como pagas porque o cliente chegou ao URL de retorno aceita uma prova que qualquer pessoa escreve à mão, como https://asuaempresa.ao/obrigado?order=1042&status=paid, e perde os pagamentos de quem fechou o separador antes de voltar. Para quem programa ou configura a integração de pagamentos de um site.

Os dois endereços, lado a lado

Critério URL de retorno URL de callback
Quem o chama O navegador do cliente. O servidor do operador.
Para que serve Mostrar uma página: obrigado, a aguardar, falhou. Mudar o estado da encomenda.
Pode-se confiar? Não. Pode ser escrito à mão, ou nunca acontecer (separador fechado, rede em baixo, telemóvel sem bateria). Sim, depois de verificar a assinatura ou de confirmar o estado na API do operador.
O que deve responder Uma página para o cliente ler. Um código 200, depressa. Ninguém lê o que lá vier.
Pode exigir sessão iniciada? Pode. Não. O operador não tem sessão no seu site, nem passa captchas.

Preparar um URL de callback que funciona

1 Use o endereço final, com HTTPS e sem redireccionamentos. Se o site redirecciona de http para https, ou de www para sem www, o POST do operador pode chegar como GET e sem corpo. Teste-o como explicado em o que é um webhook e como o testar com o curl: deve responder sem 301 nem 302.
2 Deixe-o fora de tudo o que trava um visitante: áreas com palavra-passe, modo de manutenção, captchas, plugins que bloqueiam pedidos sem navegador. Se o operador recebe 403, veja os erros 500, 403, 404 e 508 e porque um IP é bloqueado pela firewall.
3 Confirme a origem antes de mexer na encomenda: verifique a assinatura (receber um webhook em PHP e verificar a assinatura) ou, se o operador não assina, use só o identificador recebido para perguntar à API dele o estado real. Nunca confie no estado nem no valor que vêm no pedido sem uma destas duas confirmações.
4 Confira o que foi pago: o valor e a moeda batem com a encomenda, e a encomenda ainda está pendente. Uma notificação repetida para uma encomenda já paga confirma-se outra vez e ignora-se: repetições e idempotência.
5 Responda depressa e trate depois. Registe cada chamada (hora, identificador, resultado da verificação) num ficheiro ou numa tabela, responda 200 e faça o trabalho pesado a seguir. Se o seu código demora, o operador pode dar o pedido como falhado e repeti-lo.
6 Na página de retorno, mostre o que o SEU servidor sabe: pago, ou «a aguardar confirmação». Nunca o que vem no endereço. Se o callback ainda não chegou, a página diz que está pendente e, quando ele chegar, o cliente recebe a confirmação por e-mail.
«O cliente pagou mas a encomenda continua pendente» quase sempre quer dizer que o callback não chegou ou foi recusado: endereço errado nas definições do operador, um redireccionamento, um bloqueio 403, ou um erro 500 no seu código. Veja o registo de erros do PHP e o painel do operador, que muitas vezes mostra as tentativas de notificação e o código que o seu site devolveu.
Ao mudar de domínio, passar para HTTPS ou mudar o caminho da loja, actualize o URL de callback nas definições do operador (ou no código, se ele vai em cada pedido). É o passo mais esquecido de uma migração, e os pagamentos continuam a entrar sem que o site dê por isso.

O operador diz que notificou o seu site e não vê nada no registo? Abra um pedido com o endereço de callback e a hora de uma notificação, e procuramos o pedido nos registos da hospedagem.

Abrir pedido de suporte

VEJA TAMBÉM

Receber um webhook em PHP e verificar a assinatura

O que é um webhook, e como testar um com curl

Síncrono ou assíncrono: porque a confirmação de um pagamento ou de um SMS chega depois

Tempos de espera, repetições e idempotência: como não cobrar duas vezes ao cliente

Como funcionam os pagamentos online: gateway, processador e conta de comerciante

Onde está o registo de erros do PHP, como o ler, e os erros que mais aparecem

PRODUTO RECOMENDADO

Alojamento de sites com cPanel

Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde 5.940,00 Kz/mês (plano de 3 anos, com cupão)

Ver planos
Esta resposta foi útil? A sua resposta ajuda-nos a melhorar este artigo.

Artigos Relacionados

PHP e Programação 359 Como mudar a versão do PHP Pode escolher em que versão de PHP o seu site corre, das mais antigas às mais recentes, e activar ou desactivar extensõe...
PHP e Programação 245 Que tecnologias correm aqui: PHP, Node, Python, Perl, jogos e os limites «O meu programador pergunta se suportam X.» Esta página responde a isso de uma vez, com nomes e versões - e diz também o...
PHP e Programação 427 Ver e ajustar a configuração do PHP: versão por pasta, extensões e phpinfo Mudar a versão do PHP de um site inteiro é fácil e está explicado em como mudar a versão do PHP. Este artigo é o passo s...
PHP e Programação 218 Os limites do PHP: memória, tempo, tamanho de upload e o que falha em silêncio «Não consigo carregar a imagem.» «A importação pára a meio.» «O menu perdeu metade dos itens depois de gravar.» São três...
PHP e Programação 259 Onde está o registo de erros do PHP, como o ler, e os erros que mais aparecem Quando um site parte, há duas maneiras de reagir: adivinhar, ou ler o que o servidor já escreveu. A segunda é mais rápid...
PHP e Programação 2 Tempos de espera, repetições e idempotência: como não cobrar duas vezes ao cliente A resposta curta: quando um pedido a uma API esgota o tempo de espera, não sabe se ele chegou. Pode ter falhado antes de...