Copie o contrato. Cole na IA. Implemente com menos ambiguidade.

És o engenheiro responsável por integrar XPayments no meu projeto.

OBJETIVO
Implementar PIX S2S usando exclusivamente o backend da aplicação.

CONTRATO XPAYMENTS
- Base URL: https://api.xpayments.digital
- Endpoint: POST /api/v1/payments/charge
- Autenticação server-side: x-api-key: process.env.XPAYMENTS_API_KEY
- Nunca expor xp_live_* ou xp_test_* no browser.
- Body JSON:
  {
    "amount": <integer em centavos>,
    "currency": "BRL",
    "payment_method_types": ["pix"],
    "reference": <ID único do pedido/tentativa>,
    "customer": {
      "name": <nome>,
      "document": <CPF/CNPJ somente números>
    },
    "metadata": {
      "order_id": <ID do pedido>,
      "description": <descrição>
    }
  }
- 500 significa R$ 5,00.
- Resposta de sucesso inclui transactionId, reference, status="pending", method="pix" e action.
- action pode conter copyPaste, pixString, qrCode, qrCodeBase64 e qrCodeUrl.
- Não criar um segundo PIX apenas para gerar QR Code: usar a action já devolvida.
- pending NÃO significa pago.
- Só entregar o pedido após confirmação final XPayments/webhook com status succeeded.

IMPLEMENTAÇÃO PEDIDA
1. Analisa primeiro a stack e a estrutura atual deste repositório.
2. Cria uma rota backend segura para iniciar PIX.
3. Guarda XPayments transactionId + reference no pedido local.
4. No frontend, mostra QR Code, Copia e Cola, botão copiar e estado pendente.
5. Cria endpoint webhook HTTPS da XPayments e processamento idempotente.
6. Nunca credites/libertes o pedido a partir do browser, redirect ou simples criação do PIX.
7. Usa variáveis de ambiente; não hardcodes segredos.
8. Mantém logs sanitizados: nunca imprimir API keys ou dados sensíveis completos.
9. Entrega as alterações completas, ficheiros modificados, variáveis de ambiente necessárias e testes.

Antes de alterar código, identifica o framework, package manager, rotas/API existentes e padrão de env do projeto. Não inventes APIs XPayments além das descritas acima.

És o engenheiro responsável por integrar o Checkout XPay no meu projeto.

OBJETIVO
Criar sessões de checkout no backend e enviar o comprador para o Checkout XPayments, mantendo credenciais privadas no servidor.

CONTRATO
- Base URL: https://api.xpayments.digital
- Criar sessão: POST /api/v1/checkout/session
- Página de pagamento: https://checkout.xpayments.digital/pay/{sessionId}
- API Key XPayments é server-side e pertence a uma Store.
- Nunca colocar xp_live_* / xp_test_* no JavaScript público.
- O retorno/redirect ao meu site é UX, não confirmação financeira.
- O estado final do pedido deve vir da Transaction/webhook XPayments.

IMPLEMENTAÇÃO PEDIDA
1. Analisa a stack/repositório e reutiliza padrões existentes.
2. Cria endpoint backend create-checkout-session.
3. Mapeia amount em minor units, currency, reference/order_id, customer e return URL conforme o contrato existente do projeto.
4. Devolve ao frontend apenas sessionId/checkout URL necessários.
5. Implementa loading, erro e prevenção de duplo clique.
6. Implementa webhook XPayments idempotente para succeeded/failed/canceled/processing.
7. Não marque pedido como pago pelo redirect.
8. Segredos apenas em env server-side.
9. Produz testes e lista de ficheiros alterados.

Se algum campo do contrato de Checkout não estiver disponível no contexto atual do projeto, não inventes: isola-o numa função/config e marca exatamente o que preciso confirmar na documentação XPayments.

És o engenheiro responsável por migrar a integração Stripe existente para XPayments Stripe-compatible.

OBJETIVO
Manter Stripe Payment Intents/Stripe.js/Payment Element, mas criar e gerir PaymentIntents através da XPayments.

SERVER-SIDE
- Base relay: https://api.xpayments.digital/api/stripe/v1
- Server key: XPAYMENTS_API_KEY = xp_test_* ou xp_live_* da Store.
- Nunca expor xp_* no browser.
- POST /payment_intents
- GET /payment_intents/:id
- POST /payment_intents/:id
- POST /payment_intents/:id/confirm
- POST /payment_intents/:id/cancel
- POST /payment_intents/:id/capture
- Requests POST usam application/x-www-form-urlencoded, como Stripe v1.
- Preservar Idempotency-Key.

BROWSER / STRIPE ELEMENTS
- O browser continua a usar Stripe.js.
- Usar a publishable key pk_test_* / pk_live_* disponibilizada pela Store XPayments.
- pk_* é pública/browser-safe; sk_*, rk_*, webhook secrets e GatewayVault credentials nunca são expostos.
- Payment Element usa o client_secret do PaymentIntent criado pelo relay.

REGRAS
1. Analisa a integração Stripe atual antes de editar.
2. Substitui a base URL das chamadas server-side Stripe Payment Intents pela XPayments.
3. Substitui a secret key server-side pela XPAYMENTS_API_KEY.
4. Mantém Stripe.js/Elements no frontend com XPAYMENTS_STRIPE_PUBLISHABLE_KEY (pk_*).
5. Nunca envie PAN/CVV ao backend XPayments.
6. Usa Idempotency-Key estável por tentativa lógica.
7. Confirma pagamentos pelo webhook/estado final, não pelo redirect.
8. Mantém compatibilidade com SCA/3DS e next_action/client_secret.
9. Não hardcodes credenciais.
10. Mostra diff/ficheiros alterados e testes de integração.

Não uses diretamente sk_test_* ou sk_live_* do provider: essas credenciais físicas são geridas no GatewayVault XPayments.

Analisa este repositório e escolhe a superfície XPayments mais adequada sem misturar contratos:

A) PIX / métodos bancários com checkout próprio -> Native S2S
   POST https://api.xpayments.digital/api/v1/payments/charge

B) Checkout provider-neutral gerido -> Checkout XPay
   POST https://api.xpayments.digital/api/v1/checkout/session
   https://checkout.xpayments.digital/pay/{sessionId}

C) Projeto já integrado com Stripe Payment Intents/Elements -> Stripe-compatible
   https://api.xpayments.digital/api/stripe/v1

SEGURANÇA
- xp_test_* / xp_live_*: server-side only.
- pk_test_* / pk_live_*: browser-safe apenas para Stripe.js/Elements.
- Nunca pedir, expor ou imprimir sk_*, rk_*, webhook secrets físicos ou GatewayVault credentials.
- amount usa minor units nas APIs de criação (500 = 5,00 na moeda).
- Store define moeda, ambiente, routing e providers.
- Finalidade financeira vem de succeeded/webhook; pending/requires_action/redirect não é liquidação.

Primeiro descreve qual das opções A/B/C corresponde ao código existente. Depois implementa a integração com o menor número de mudanças possível, mantendo idempotência, webhooks, logs sanitizados e env vars.