Mobile Paywall Checkout

Mobile Paywall & Checkout — Seleção de Plano e Pagamento em Apps

Ajudar o usuário a escolher um plano antes de pedir que ele resolva o pagamento. O plano-alvo pode ter mais hierarquia visual; preço, periodicidade, renovação e alternativas nunca podem ser ocultados ou apresentados de forma enganadora.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/evals.md e policies/anti-ai-writing.md (microcopy de checkout é prosa que usuário lê — passa por /humanize).

Fronteira com skills vizinhas — esta skill decide a interface e o fluxo de decisão do usuário. Não reimplementa:

• skills/60-app-reference-architecture/SKILL.md — modelo de dados unificado de pagamento (tabela Subscription, grace_period, RTDN, reconciliação, ledger de créditos, multi-provider registry pattern). Esta skill 63 consome esse modelo para decidir a UI; não duplica o schema nem a lógica de webhook. docs/skill-guides/app-reference-architecture/04-pagamentos.md é a fonte de verdade do lado backend
• skills/02-ui-ux-design/SKILL.md — leis cognitivas, dark patterns, três camadas de token, hierarquia visual geral. Esta skill 63 aplica esses princípios ao domínio específico de paywall, não os reescreve
• skills/02-ui-ux-design/references/marketing-surfaces.md — página de preço pública, sem SDK, sem transação real (marketing). Esta skill 63 é o paywall in-app com checkout de verdade — o usuário já está no app, a tela abre um PaymentSheet/purchase sheet
• skills/57-mobile-ux-foundations/SKILL.md — thumb zone, dark mode físico, performance percebida. Esta skill 63 herda esses fundamentos sem repetir
• skills/22-accessibility-specialist/SKILL.md — WCAG geral. Esta skill 63 só declara os requisitos específicos de touch target e semantics de componente de pagamento
• skills/06-security-review/SKILL.md — fronteira PCI (PAN/CVV nunca persistidos, nunca em log/analytics) é regra de segurança que esta skill cita mas não é dona

Quando Usar

• desenhar ou revisar a tela de seleção de plano/assinatura de um app mobile
• decidir se o checkout usa Google Play Billing, Google Pay, ou PSP externo (Stripe, Mercado Pago)
• posicionar e desenhar o campo de cupão/desconto no checkout
• especificar os estados de pagamento (processing, 3DS, pending, erro, sucesso)
• definir hierarquia visual do plano recomendado sem cair em dark pattern
• montar plano de A/B testing e funil de métricas de um paywall

Quando Não Usar

• desenhar página de preço pública sem transação real — references/marketing-surfaces.md da skill 02
• implementar o schema de dados, webhook ou reconciliação de pagamento — skill 60
• decisão de pricing/monetização do produto (quanto cobrar, quais tiers existem) — skill 01, seção de monetização
• checkout de e-commerce de produto físico — este domínio é assinatura/conteúdo digital in-app

Modelo Conceptual — Quatro Entidades Que Não Se Misturam

Card que mistura tudo ("PRO ANUAL 30% OFF CARTÃO") aumenta o número de conceitos que o usuário compara de uma vez — o oposto de Hick-Hyman (skill 02). Decisão progressiva: periodicidade → plano → oferta/cupão → pagamento, cada uma numa etapa visual clara.

No Google Play, essa separação tem correspondência técnica direta: uma subscrição pode ter múltiplos base plans (ex: mensal, anual) e múltiplas offers associadas a cada um — detalhe completo em docs/skill-guides/mobile-paywall-checkout/01-billing-decision.md.

Decisão de Arquitetura de Cobrança — Antes de Desenhar Qualquer Tela

Esta decisão não é visual — precisa ser resolvida antes do wireframe, porque muda o fluxo inteiro (paywall próprio + purchase sheet do Play vs. dois telas customizadas com PSP).

Detalhe completo (matriz por mercado, promo code Play vs. cupom de comerciante, tokenização/PCI, idempotência) em docs/skill-guides/mobile-paywall-checkout/01-billing-decision.md.

Regra dura: um app que vende funcionalidade digital dentro do APK publicado na Play Store e desenha [ Pagar com Stripe ] sem checar elegibilidade não é uma decisão de design — é risco de política de plataforma. Esta decisão vai para Product/Payments antes do handoff para Frontend.

Fluxo de Referência

escolher periodicidade → escolher plano → rever preço/desconto →
  → (opcional) aplicar cupão → pagar → autenticar se necessário → confirmar

Periodicidade aparece antes dos cards porque reinterpreta o preço de todos eles. Ao trocar mensal↔anual, o tier selecionado é preservado — a pergunta "que produto eu quero" não mudou, só a frequência de cobrança mudou. Perder a seleção nessa troca é bug de UX, não comportamento neutro.

Preço anual: o total anual tem que ser pelo menos tão proeminente quanto o equivalente mensal. "4,99€/mês" gigante com o total anual escondido numa nota é o antipadrão mais citado nas políticas de subscrição Google — ver dark patterns na skill 02. Formato correto: "59,99€/ano · equivale a 5,00€/mês · Renovação anual até cancelamento.".

Wireframes completos por estado (inicial, selecionado, cupão aberto/aplicado/erro, processing, 3DS, pendente, sucesso) em docs/skill-guides/mobile-paywall-checkout/02-plan-selection-ui.md.

Cupão — Collapsed, Não Aberto Por Padrão

A recomendação mais forte deste domínio: campo de cupão recolhido atrás de um link ("🏷 Tem um cupão?"), nunca um input [____] [Aplicar] permanentemente visível.

Um campo de cupão sempre visível sinaliza ao usuário que existe um preço melhor em algum lugar, e usuários sem código saem do checkout pra procurar um — é o achado central da pesquisa de checkout da Baymard sobre esse padrão. Auto-aplicar desconto elegível (via deep link, campanha reconhecida) é preferível a pedir digitação manual sempre que tecnicamente possível.

Posição: depois do resumo de preço, antes do total — nunca antes da escolha do plano (introduz "caça a desconto" antes do usuário saber o que quer comprar).

Código Google Play ≠ cupão de comerciante. Promo codes do Play concedem teste grátis de subscrição, não um motor genérico de "25% off". Nunca prometer na UI um desconto que o sistema de billing autorizado não vai efetivamente cobrar — mostrar "25% aplicado" e o purchase sheet exibir o preço cheio é quebra de confiança e viola a exigência de consistência das políticas Play.

Comparação completa das 4 alternativas de posicionamento (collapsed / aberto / modal / auto-aplicação) com evidência e risco de cada uma em docs/skill-guides/mobile-paywall-checkout/03-coupon-ux.md.

Hierarquia do Plano-Alvo — Sem Manipulação

O plano que o negócio quer vender pode receber destaque através de sinais cumulativos, nunca manipulativos: badge ("Recomendado", só se for recomendação real), borda/superfície de maior peso, benefícios diferenciadores mais visíveis. Pré-seleção é hipótese de produto a testar, não recurso pra esconder a escolha — os demais planos continuam legíveis, nunca reduzidos a texto cinza minúsculo.

Badge tem semântica que não pode ser inventada: "Mais Popular" exige dado real de escolha por outros usuários; "Recomendado para Você" exige sinal individual justificável; "Recomendado" sozinho é recomendação editorial do produto. Usar qualquer um sem lastro é o mesmo tipo de fabricação que skills/02-ui-ux-design/references/audit-framework.md já proíbe na auditoria — aqui, na criação.

Estados de Pagamento

Máquina de estados mínima: Ready → Submitting → Authenticating (3DS) → Pending → Succeeded | Failed → Reconciling.

Regra fundamental: "o usuário voltou da autenticação 3DS" não é sinônimo de "pagamento aprovado" nem de "recusado". Depois do retorno (deep link, callback do SDK), a tela mostra "A confirmar pagamento…" e consulta o estado autoritativo antes de declarar sucesso ou falha — nunca assume pelo simples fato de ter retornado. Checkpoint: se a consulta ao estado autoritativo não retornar em tempo hábil (timeout, rede instável), permanecer em Reconciling e reconsultar com backoff — nunca inferir sucesso/falha pela ausência de resposta, e nunca deixar o usuário preso na tela sem indicação de que a verificação continua em andamento.

Erro de pagamento nunca obriga o usuário a repetir trabalho que já foi validado (plano, cupão) — preservar tudo, mostrar mensagem específica e acionável, oferecer retry ou troca de método. Anti-duplo-submit é obrigatório: PaymentIntent do Stripe leva idempotency key associada à mesma sessão/compra pra impedir cobrança duplicada em retry técnico.

Estados completos, microcopy por caso, e taxonomia de erro (issuer_declined, authentication_failed, network_error, etc., nunca só payment_failed genérico) em docs/skill-guides/mobile-paywall-checkout/04-payment-states.md.

Acessibilidade e Componentes

Touch target mínimo 48×48dp em toda área interativa crítica (radio de plano, remover cupão, segmento de periodicidade, CTA) — mesmo quando o glyph visual é menor. Seleção de plano nunca depende só de cor: borda/superfície + radio selecionado + semantics selected=true juntos. Ordem de leitura para leitor de tela segue a lógica visual (título → periodicidade → planos → cupão → resumo → termos → CTA), nunca deixando a barra sticky de CTA ser lida fora de ordem.

Especificação completa de semantics/TalkBack, autofill, tipo de teclado por campo, e validação (nunca prematura — validar no blur/submit, não no primeiro caractere) em docs/skill-guides/mobile-paywall-checkout/05-accessibility-components.md.

Experimentação e Métricas

O objetivo do A/B testing aqui não é maximizar clique — é aumentar aquisição correta e sustentável sem gerar arrependimento, cancelamento ou chamado de suporte depois. Todo teste de pré-seleção, badge ou ordem de plano precisa de guardrail de troca de plano/refund/cancelamento, não só a métrica de conversão isolada.

Funil mínimo: Paywall view → Plan selected → Checkout CTA → Payment UI opened → Auth se necessária → Payment confirmed. Dicionário de eventos, definição de cada métrica de funil, e o teste prioritário (cupão collapsed vs. aberto) em docs/skill-guides/mobile-paywall-checkout/06-experimentation-metrics.md.

QA e Implementação

Matriz de QA (troca de periodicidade preserva tier, duplo tap gera 1 compra só, process death reconcilia ao voltar, 3DS cancelado preserva dados, TalkBack, escala de fonte grande, teclado aberto não esconde CTA) e uma timeline de referência de 6 semanas em docs/skill-guides/mobile-paywall-checkout/07-qa-and-timeline.md.

Evidência de Conclusão

• decisão de billing (Play Billing vs. PSP) documentada e aprovada por Product/Payments antes do handoff de UI
• as 4 entidades (tier, periodicidade, oferta, pagamento) aparecem como decisões visuais separadas, nunca fundidas num único card
• campo de cupão é collapsed por padrão, com posição definida (após resumo, antes do total)
• todo estado de pagamento (processing, 3DS, pending, erro, sucesso) tem tela/microcopy própria — nenhum "pagamento concluído" otimista antes de confirmação autoritativa
• plano-alvo tem hierarquia declarada com sinais reais (badge com lastro, não fabricado)
• touch target ≥48×48dp verificado nos componentes de pagamento
• funil de eventos instrumentado com o dicionário de 06-experimentation-metrics.md

Handoff

• App Reference Architecture (60): schema de dados, webhook, reconciliação, multi-provider registry — esta skill consome, não duplica
• UI/UX Design (02): leis cognitivas, dark patterns, tokens — aplicados aqui ao domínio específico
• Security Review (06): fronteira PCI (PAN/CVV) antes de qualquer implementação de coleta de cartão própria
• QA Engineer (05): matriz de QA de 07-qa-and-timeline.md vira suíte de teste
• Data Analytics (21): dicionário de eventos do funil de pagamento

Integração com Pipeline

• Orchestrator (09): aciona esta skill quando a tarefa é paywall/checkout de app mobile, distinta de arquitetura de app nova (60) ou página de preço pública (02)
• Documenter (10): registra a decisão de billing (Play Billing vs. PSP) como ADR — não é reversível sem custo depois do lançamento

Fontes

• Design doc próprio do usuário sobre seleção de planos e checkout de pagamento em Android (estado das fontes: 15 de agosto de 2026), cobrindo Google Play Billing, Google Pay, Stripe e Mercado Pago — curado e modularizado em docs/skill-guides/mobile-paywall-checkout/, mantendo os wireframes, a matriz de decisão e o plano de experimentação do documento original.