Como integrar o Payora a um site PHP personalizado

Como conectar o Payora a um site PHP personalizado

Se o seu site foi desenvolvido em PHP sem uma plataforma pronta, o processo é simples: crie um pagamento, encaminhe o cliente ao Payora e, depois, traga o resultado de volta para o seu sistema de pedidos. Não precisa do WooCommerce nem de uma confusão de plugins.

Este guia mostra como integrar o Payora a um site PHP sem transformar o checkout num projeto de ciência. Você vai ver exatamente onde o PHP deve iniciar o pagamento, onde deve receber o retorno e onde o seu aplicativo deve decidir se o pedido está pago, pendente ou falhou.

1. Confirme o padrão de integração para um site PHP personalizado

Comece por uma decisão: você vai criar um link de pagamento simples, uma solicitação de pagamento no servidor ou um fluxo completo com acompanhamento do pedido? Não são a mesma coisa. Um site de doações de uma página pode funcionar com um link de pagamento, enquanto uma loja com 20 produtos geralmente precisa criar o pedido no servidor antes de o cliente sair do site.

Para um site PHP personalizado, o padrão mais simples costuma ser: criar o pedido localmente, gerar o pagamento do Payora em PHP, redirecionar o cliente e, em seguida, receber o retorno e a confirmação do servidor. Assim, você registra o pedido antes de o dinheiro ser movimentado. Além disso, a lógica do carrinho e das faturas continua dentro do seu aplicativo, onde deve ficar.

Se o seu checkout for bem simples, talvez baste redirecionar o cliente para uma página de pagamento hospedada pelo Payora. Se você precisar de itens detalhados, observações do cliente ou IDs de pedido, o código PHP deverá enviar esses dados antes do redirecionamento. Simples, mas não simplista. Em ambos os casos, o fluxo explica como criar checkout em PHP com Payora de acordo com as necessidades do seu site.

Um exemplo prático ajuda. Uma agência digital que vende um pacote de manutenção em 3 etapas pode criar o pedido em PHP, adicionar o e-mail do cliente e encaminhá-lo ao Payora com a referência da fatura. Já um projeto pessoal que vende uma única chave de licença talvez precise apenas do link de pagamento e de uma página de retorno. A diferença está na quantidade de informações de estado que você precisa preservar, não na quantidade de código.

2. Defina as páginas, os endpoints e o fluxo de sessão

Antes de escrever código, liste as páginas. Você precisa de pelo menos três: uma página de checkout, uma página de retorno e um endpoint no servidor para confirmar o pagamento. Se você não mapear o fluxo, vai acabar tentando adivinhar qual solicitação alterou o pedido. E adivinhar sai caro.

Use uma sessão PHP comum para o fluxo no navegador, mas não confie apenas nela. O estado da sessão pode se perder se o cliente trocar de dispositivo, fechar a aba ou voltar do Payora mais tarde. Salve também o ID do pedido no banco de dados, para que o código PHP encontre a transação mesmo que a sessão do navegador não esteja mais disponível.

Um fluxo típico é assim:

• A página de checkout coleta o produto, o e-mail e a quantidade.
• O PHP cria um pedido local com o status pendente.
• O PHP encaminha o cliente ao Payora.
• O Payora redireciona o navegador para o URL de retorno.
• O servidor verifica o status do pagamento antes de marcar o pedido como pago.

Esse fluxo mantém a página de retorno do navegador separada da confirmação do servidor. Ótimo. Elas devem ser separadas. O navegador pode informar o que o cliente viu; o servidor é que deve decidir o que isso significa para o pedido.

Um pequeno hábito pode poupar horas mais tarde: salve a referência do pagamento Payora junto ao ID do pedido assim que criar o pagamento. Se você esperar até depois do redirecionamento, um erro de rede ou uma atualização impaciente da página pode deixar você com um pedido, mas sem a referência do Payora. Aí começa o trabalho de detetive em produção.

3. Prepare uma camada simples de solicitação de pagamento em PHP

Mantenha o código de pagamento fora dos templates. Uma classe PHP pequena ou uma função auxiliar já basta. Um método pode montar os dados da solicitação, outro pode enviar a requisição HTTP e um terceiro pode interpretar a resposta. Essa separação importa porque a lógica de pagamento muda com mais frequência do que a marcação das páginas.

Por exemplo, a função auxiliar pode receber um array com amount, currency, order_id e return_url e, em seguida, adicionar as credenciais do Payora a partir das variáveis de ambiente. A página de checkout nunca deve saber onde fica o token da API. Só precisa saber qual botão foi clicado.

Veja a estrutura da lógica do código — não uma implementação completa:

1. Leia o pedido no banco de dados.
2. Monte um array de solicitação para o Payora.
3. Envie a solicitação com cURL ou um cliente HTTP semelhante.
4. Salve a referência do pagamento retornada pelo Payora.
5. Redirecione o cliente para o URL de pagamento do Payora.

Mantenha essa função auxiliar simples e sem surpresas. Código simples é mais fácil de testar e tende a dar menos problemas quando você altera o preço de um produto ou adiciona outro formulário de checkout no mês seguinte.

Se o seu aplicativo já tiver uma abstração para pagamentos, use-a. Caso contrário, crie um arquivo e dê a ele um nome claro, como PayoraClient.php. Esse arquivo deve conter as credenciais, as chamadas à API e a interpretação das respostas. Nada mais. Sem HTML. Sem CSS. Sem mensagem de agradecimento.

4. Encaminhe o cliente ao Payora pelo seu checkout personalizado

Depois de criar o pedido local, envie a solicitação de pagamento ao Payora e encaminhe o cliente para a página de pagamento. A transferência só deve acontecer depois que o servidor salvar o pedido, pois o usuário pode fechar a aba assim que o redirecionamento começar.

Envie apenas os dados do pedido de que você realmente precisa. Normalmente, isso inclui o ID do pedido, o valor, a moeda e o e-mail do cliente. Você também pode enviar metadados, como o nome do produto ou o ID de uma conta interna, mas não inclua todos os campos do banco de dados só porque estão disponíveis. Dados extras podem gerar confusão depois, quando a equipe de suporte comparar os registros.

Um checkout personalizado costuma usar um formulário POST com um botão “Pagar agora”. Esse formulário envia os dados ao endpoint PHP, que cria o pagamento no Payora e, em seguida, responde com um redirecionamento. O cliente não vê a resposta da API — só vê o Payora.

Um cuidado: não confie nos totais calculados no cliente. Se a página do produto mostra US$ 49, mas o navegador envia US$ 39, o servidor deve rejeitar a divergência. A solicitação de pagamento deve usar o total do pedido registrado no servidor, não o valor de um campo oculto do formulário. Essa regra é importante sempre.

Se quiser ter uma visão mais ampla dos padrões de configuração de pagamentos, o guia sobre gateway de pagamento em criptomoedas para e-commerce oferece um contexto útil sem repetir aqui o fluxo em PHP.

5. Receba e valide o resultado do pagamento no seu aplicativo

O URL de retorno no navegador é útil, mas não é a palavra final. Ele pode informar que a página de pagamento foi acessada e trazer um valor de status, mas o seu aplicativo PHP ainda deve tratar esse resultado como provisório até receber a confirmação do servidor. Pendente não significa pago.

Prepare a página de retorno para lidar com três casos: sucesso, pendente e falha. Se o Payora indicar sucesso, mostre uma página de agradecimento e informe ao usuário que o pedido está sendo confirmado. Se o status estiver pendente, diga isso claramente. Se o pagamento falhar, convide o cliente a tentar novamente sem perder o registro do pedido. Uma mensagem clara reduz os chamados de suporte.

Uma regra importante: a página de retorno nunca deve marcar o pedido como pago por conta própria. Ela deve apenas mostrar o estado atual e, se necessário, oferecer um link para voltar à página do pedido. A atualização do banco de dados acontece após a verificação, não depois de um redirecionamento no navegador. Essa diferença protege você contra atualizações duplicadas acidentais.

Deixe o endpoint de retorno simples o bastante para ser entendido num relance. Se ele receber uma referência de pagamento do Payora, consulte-a. Se a referência estiver ausente, registre a solicitação nos logs e interrompa o processamento. Se o pedido já estiver pago, mostre uma mensagem simpática e não altere nada. É assim que fluxos idempotentes continuam estáveis mesmo quando a página é atualizada repetidamente.

Para equipes que também querem comparar o fluxo com o checkout, o artigo sobre como aceitar pagamentos em criptomoedas traz observações úteis sobre cobrança, especialmente se você vende serviços com faturas recorrentes ou aprovações manuais.

6. Confirme a transação no servidor antes de marcar o pedido como pago

Esta é a etapa mais segura. Seu aplicativo PHP deve consultar o Payora no servidor e confirmar o status da transação antes de marcar o pedido como pago. Um redirecionamento do navegador pode omitir informações; as verificações do servidor não dependem de o cliente ter fechado a aba, atualizado a página duas vezes ou usado outro dispositivo. É assim que se confirma o pagamento com segurança: como confirmar pagamentos do Payora em PHP depende de uma verificação feita pelo servidor, não apenas do retorno no navegador.

Use a referência do pagamento Payora que você salvou anteriormente e solicite o estado atual da transação. Compare o status retornado com o status necessário para processar o pedido. Se a transação estiver liquidada ou confirmada, atualize o pedido. Se estiver pendente, mantenha-o pendente. Se tiver falhado ou sido cancelada, não altere o pedido.

Um comentário à parte: é nesta etapa que muitos sites PHP personalizados acabam descuidando da implementação. Confiam na página de retorno porque é mais rápido programar assim. Mais rápido, sim. Mais seguro, não. Uma verificação de 5 segundos vale mais do que uma longa troca de e-mails com o suporte depois. Sempre.

Se o Payora oferecer um callback assinado ou um mecanismo de confirmação entre servidores, use-o junto com a consulta do status. Assim, você tem duas verificações: uma no fluxo do cliente e outra no fluxo do servidor. Se a sua implementação precisar de uma verificação de assinatura passo a passo, consulte como testar um pagamento em criptomoedas para ver o rigor de validação que faz toda a diferença antes do lançamento.

Só marque o pedido como pago quando o servidor confirmar. Não quando o cliente disser que pagou. Nem quando o navegador disser. O banco de dados deve refletir o estado do pagamento confirmado pelo Payora, pois é esse estado que as equipes de processamento de pedidos e contabilidade vão considerar confiável mais tarde.

7. Salve os dados do pagamento e trate envios duplicados

Salve no banco de dados a referência da transação Payora, o ID do pedido local, o valor, a moeda e o status final. Se possível, faça isso em uma única gravação. Quando um cliente enviar um e-mail dizendo “paguei duas vezes”, você vai querer encontrar um registro claro, não três atualizações pela metade.

Envios duplicados acontecem por motivos comuns. O cliente clica duas vezes. Usa o botão Voltar. O navegador tenta enviar a solicitação novamente. Seu código PHP deve detectar se o pedido já tem uma referência do Payora e impedir a criação de um segundo pagamento para o mesmo pedido, a menos que o primeiro tenha falhado ou expirado. Esse é o princípio da idempotência.

Uma regra simples funciona bem: um pedido local, uma transação Payora ativa. Se chegar uma segunda solicitação para o mesmo pedido enquanto a primeira estiver pendente, mostre o link de checkout Payora já existente em vez de criar outro. Se o pedido já estiver pago, não faça nada. Sem alarde. Esse silêncio é intencional.

Use nomes específicos para as colunas do banco de dados. Por exemplo, mantenha payora_reference, payment_status, paid_at e last_checked_at. Esses campos ajudam as equipes de suporte, contabilidade e depuração. Se mais tarde você precisar reconciliar um pagamento, esses quatro campos poderão responder à maioria das perguntas sem que seja necessário passar uma hora vasculhando os logs.

Se você estiver criando um fluxo de faturamento para clientes, e não um checkout de loja, o artigo sobre gateway de pagamento em criptomoedas para freelancers também pode ajudar com a mesma lógica de registro, especialmente quando os números das faturas são mais importantes do que os carrinhos.

8. Teste o fluxo completo numa cópia de homologação do site

Antes de entrar em produção, clone o site para um ambiente de homologação e teste todo o fluxo: criação do pedido, redirecionamento ao Payora, página de retorno, verificação do servidor e tratamento de cliques duplicados. Se você testar apenas o redirecionamento, terá testado só um terço do problema.

Faça pelo menos estes testes:

• Crie um pedido novo e confirme que a solicitação de pagamento do Payora foi gerada.
• Atualize a página de retorno 2 vezes e confirme que o pedido não é alterado novamente.
• Envie o formulário de checkout duas vezes e verifique se existe apenas 1 transação ativa.
• Force um resultado pendente ou com falha e confirme que o pedido continua sem ser marcado como pago.
• Verifique se a referência do Payora salva corresponde ao registro no banco de dados.

Teste com a mesma versão do PHP e a mesma configuração de servidor que pretende usar em produção. Um fluxo que funciona no computador local pode falhar num servidor de produção com uma configuração SSL mais rigorosa ou uma opção diferente do cURL. Isso não é raro. Acontece.

Mais um teste prático: abra o pedido numa janela anônima, conclua o pagamento e, em seguida, abra o mesmo URL de retorno noutro navegador. Seu aplicativo não deve atualizar o pagamento uma segunda vez. Se isso acontecer, corrija antes de lançar. Sem exceções.

Para equipes que oferecem opções de checkout com USDC junto a outros métodos de pagamento, as observações em como aceitar pagamentos em USDC podem ajudar a comparar as expectativas dos clientes antes de levar o fluxo em PHP para produção.

E aqui vai a última verificação: o mesmo pedido deve passar por um redirecionamento, uma atualização de página e uma confirmação do servidor sem sair de sincronia. Se isso acontecer, seu checkout PHP personalizado estará pronto para o primeiro pagamento real.