Entenda checkout de planos e pacotes de créditos da Rivya, redirecionamentos do Stripe, a ponte /payment, webhooks, atualizações de cobrança e verificações de compra.

Use este guia de checkout de pagamento quando precisar entender o que acontece depois de comprar um plano ou pacote de créditos na Rivya.

O que as pessoas costumam entender errado sobre pagamento na Rivya é isto:

o Stripe concluir o pagamento não é a última etapa. O produto ainda precisa alcançar essa mudança e refleti-la corretamente.

É por isso que o fluxo de checkout não termina no Stripe e não termina no momento em que o navegador volta.

O Fluxo De Pagamento Tem Três Etapas Reais

Agora, o checkout fica mais fácil de entender se você o divide em três etapas:

a Rivya cria a sessão de checkout
o usuário conclui o Stripe Checkout
a Rivya espera o estado do produto voltar a ser confiável

Essa terceira etapa é exatamente o motivo pelo qual /payment existe.

Onde O Checkout Pode Começar

Atualmente, o checkout começa em lugares que já combinam com a intenção do usuário:

Preços
/settings/billing
/settings/credits

E os dois principais formatos de compra são:

checkout de plano de assinatura
checkout de pacote avulso de créditos

Essas são decisões comerciais diferentes, mas ainda convergem para o mesmo caminho de confirmação.

Checkout De Plano E Checkout De Pacote De Créditos São Parecidos, Mas Não Iguais

Checkout de plano tem formato de assinatura.

Checkout de pacote de créditos tem formato de recarga avulsa da carteira.

Essa diferença importa porque, depois do pagamento, a Rivya precisa saber se deve atualizar:

estado da assinatura
ou estado da carteira

É por isso que o mesmo momento de sucesso no Stripe ainda pode enviar você de volta para superfícies diferentes do produto depois.

Por Que `/payment` Existe

/payment não é uma página de recibo no sentido usual.

É uma ponte de processamento.

Sua função é:

ler o session_id do Stripe
verificar se o registro de pagamento do lado do produto foi liquidado
continuar consultando por um curto período, se necessário
só então redirecionar você de volta para a parte certa do app

Isso a torna mais parecida com uma página de sincronização de estado do que com uma página de conteúdo.

Quando Um Pagamento Está "Realmente Concluído" Da Perspectiva Do Produto?

Do ponto de vista do usuário, o pagamento parece concluído quando o Stripe diz que funcionou.

Do ponto de vista do produto, o pagamento só está realmente concluído quando o estado da conta está visivelmente atualizado na Rivya.

Isso geralmente significa:

o registro de pagamento está marcado como pago ou concluído
efeitos de assinatura ou carteira estão visíveis
você pode retornar com segurança para cobrança ou créditos sem ver estado desatualizado

Esse é o verdadeiro motivo pelo qual o produto espera em /payment em vez de jogar o usuário imediatamente de volta para o app.

Por Que Webhooks Ainda Importam Mesmo Que `/payment` Faça Polling

/payment não substitui webhooks do Stripe.

Webhooks ainda são o que atualiza o estado durável do backend.

A página /payment existe para que a experiência possa esperar até que esse estado esteja refletido bem o suficiente para ser confiável antes de redirecionar.

Essa é a diferença entre:

"o Stripe processou algo"
e "a Rivya agora reflete claramente essa mudança"

Para Onde Você Vai Depois Do Pagamento

O caminho de retorno é intencionalmente ligado ao que mudou.

Se a compra foi relacionada a assinatura, em geral você é enviado de volta para cobrança.

Se a compra foi um pacote de créditos, em geral você é enviado de volta para créditos.

Isso não é roteamento cosmético. Ele combina com a pergunta que usuários geralmente têm logo depois de pagar:

meu plano foi atualizado?
ou minha carteira foi atualizada?

O Que Um Timeout Ou Falha Realmente Significa

Se /payment expirar ou falhar, isso não significa automaticamente que o pagamento em si desapareceu.

Com mais frequência, significa uma destas coisas:

o registro de pagamento do lado do produto ainda não foi liquidado
o redirecionamento está esperando por um estado que ainda está se atualizando
a página da conta ainda pareceria desatualizada se o usuário fosse redirecionado cedo demais

É por isso que um estado de timeout é melhor do que um falso estado de sucesso. Ele diz ao usuário que a confirmação do produto é a parte que ainda está incompleta.

A Melhor Forma De Verificar Se O Pagamento Realmente Entrou

Depois do checkout, o caminho de verificação mais limpo é:

deixar /payment concluir seu fluxo
verificar /settings/billing se a compra foi um plano
verificar /settings/credits se a compra foi um pacote
verificar a Central de Notificações se a conta ainda parecer fora de sincronia

Isso geralmente é melhor do que atualizar páginas aleatórias e adivinhar.

Pagamento Também Vira Memória Da Conta

Pagamento não é apenas uma ação de checkout. Ele também se torna parte do histórico da conta por meio de eventos duráveis como:

assinatura iniciada
assinatura renovada
pagamento falhou
pacote de créditos adicionado

É por isso que notificações também importam aqui. Fechar a aba do Stripe não é o fim da história da conta.

Um Modelo Mental Melhor

A forma mais simples de pensar no checkout da Rivya é:

Stripe cuida da movimentação do dinheiro
/payment cuida da reentrada do lado do produto

Se você mantiver esses dois papéis separados, o fluxo inteiro fica mais fácil de entender.

Checklist De Estado Do Checkout

Quando uma compra parecer inacabada ou confusa, confira:

Confirme onde o Checkout começou: preços públicos, configurações de cobrança ou configurações de créditos.
Confira se o Stripe concluiu o pagamento e retornou o usuário para /payment.
Aguarde a Rivya atualizar assinatura, pacote, fatura e estado da carteira antes de iniciar outra tarefa paga.
Use páginas de cobrança para assinaturas e páginas de créditos para pacotes ou histórico da carteira.
Não trate um redirecionamento do navegador como prova de que webhook e estado da conta já foram liquidados.

Reconfira Antes De Tentar Pagar Novamente

Reconfira antes de tentar pagar novamente se o usuário vir um plano desatualizado, créditos ausentes, janelas duplicadas de Checkout, pagamento falhou ou um recibo bem-sucedido do Stripe que ainda não aparece na Rivya.

Guia de Checkout de Pagamento da Rivya