biz-setup-sepay-payment

Biz Setup Sepay Payment — Infrastructure de paiement VietQR bout en bout pour Next.js

Ce skill construit l'infrastructure de paiement complète pour une landing page Next.js utilisant Sepay (passerelle de paiement VietQR Vietnam). Une fois terminé : le client remplit un formulaire → création d'une commande → scan du QR → transfert bancaire → webhook Sepay → vérification + recherche du lead + déclenchement email/telegram. Entièrement automatisé, sans confirmation manuelle par l'administrateur.

Philosophie : Sepay est le chemin de moindre résistance pour le Vietnam — VietQR + API bancaire native, pas besoin d'inscription pour le client, scan du QR avec l'application bancaire existante. Frais de 1.5-2% moins chers que Stripe (4-5%), règlement T+1, offre gratuite raisonnable pour des landing pages < 100 commandes/mois.

Pourquoi un stockage de leads ? : Le webhook Sepay envoie uniquement content (texte copié par le client lors du virement) + montant. Sepay NE sait PAS qui est le client. Il faut un stockage de leads local pour mapper content → lead {name, phone, email, product, amount}.

2 options de stockage de leads — l'utilisateur choisit à la Phase 0 :

• Vercel KV (Upstash Redis) — configuration en 2 minutes, TTL natif, 30 000 commandes/mois gratuites → < 500 commandes/mois
• Supabase Free (Postgres) — configuration en 5 minutes, requêtes SQL + interface Studio, offre gratuite ~50× plus large → < 2000 commandes/mois. RECOMMANDÉ.

Les routes API (/api/checkout, /api/sepay-webhook, /api/admin/leads) sont indépendantes du fournisseur de stockage via lib/leads-store.ts (réexportation légère). Changer de fournisseur ultérieurement = modifier une seule ligne.

Le skill NE crée PAS lui-même un compte Sepay pour l'utilisateur (nécessite KYC professionnel + compte bancaire). Le skill guide l'utilisateur étape par étape, puis connecte l'ensemble du code.

---

Quand utiliser ce skill

• L'utilisateur lance un produit numérique / cours / coaching et a besoin d'accepter des paiements en ligne.
• L'utilisateur a déjà une landing page Next.js (via ui-ux-pro-max ou équivalent) et souhaite ajouter un flux de paiement.
• L'utilisateur s'apprête à connecter biz-email-setup ou biz-telegram-payment-notify mais n'a pas encore d'infrastructure de paiement → ce skill est un PRÉREQUIS.

NE PAS utiliser ce skill lorsque:

• L'utilisateur utilise Stripe/PayPal (paiement par carte internationale) → cas d'usage différent.
• L'utilisateur accepte les virements manuels + vérifie lui-même (faible volume, déconseillé).
• L'utilisateur a déjà une infrastructure de paiement et a seulement besoin de notifications → aller directement à /biz-email-setup ou /biz-telegram-payment-notify.

---

Flux de travail général (7 phases)

Phase 0 : DÉTECTION du stack Next.js + DEMANDE du fournisseur (KV / Supabase) — POINT DE CONTRÔLE
       ↓
Phase 1 : GUIDER l'utilisateur pour configurer un compte Sepay — POINT DE CONTRÔLE manuel, attendre que l'utilisateur termine
       ↓
Phase 2A (si KV) : CONFIGURER Vercel KV (installation du package + variables d'environnement + namespace KV)
Phase 2B (si Supabase) : CONFIGURER Supabase (création du projet + migration SQL + service_role)
       ↓
Phase 3 : CRÉER lib/leads-store.ts (wrapper réexportation) + lib/leads-{kv|supabase}.ts (implémentation)
       ↓
Phase 4 : CRÉER la route /api/checkout (formulaire → commande → stockage)
       ↓
Phase 5 : CRÉER la route /api/sepay-webhook (vérification + recherche + espace réservé pour effets de bord)
       ↓
Phase 6 : INTÉGRER VietQR dans la landing page (choisir 1 des 3 modèles UX)
       ↓
Phase 7 : PLAN DE TEST en 5 niveaux (stockage → checkout → webhook → production → (Supabase uniquement) ping cron)

Les Phases 0 et 1 ont des points de contrôle qui attendent l'utilisateur. Les Phases 2/3/4/5/6 sont exécutées activement par le skill.

---

Phase 0 — Détection du stack Next.js + sélection du fournisseur

0.1 Détection du stack

test -f next.config.js -o -f next.config.mjs -o -f next.config.ts && echo "Next.js: ✓"
test -d app && echo "Router: App"
test -d pages && echo "Router: Pages"
test -f tsconfig.json && echo "TS: ✓"
test -f pnpm-lock.yaml && echo "pkg: pnpm" || test -f yarn.lock && echo "pkg: yarn" || echo "pkg: npm"

Si ce n'est pas Next.js : ARRÊTER. Signaler : "Ce skill ne supporte actuellement que Next.js. Votre stack actuel est [X]. Je peux porter la logique vers Vite/statique avec une fonction Vercel ?" — attendre l'utilisateur.

Si app/ ET pages/ existent : demander à l'utilisateur lequel utiliser.

0.2 Vérification de l'infrastructure existante

ls app/api/ pages/api/ lib/ 2>/dev/null
grep -E '"@vercel/kv"|"@supabase/supabase-js"|"@upstash/redis"' package.json
grep -E "SEPAY|KV_REST|SUPABASE_" .env.local 2>/dev/null

0.3 DEMANDER à l'utilisateur de choisir le fournisseur

J'ai détecté que vous utilisez Next.js [App/Pages] Router + TypeScript + [pnpm/yarn/npm].

Où souhaitez-vous stocker les leads ?

1. Vercel KV (Upstash Redis)
   ✓ Configuration rapide en 2 minutes (1 clic dans le dashboard Vercel)
   ✓ TTL natif — pas de souci de mise en pause du projet
   ✗ Gratuit : seulement 30 000 commandes/mois → ~500 commandes/mois
   ✗ Pas de SQL — filtrage admin complexe difficile

2. Supabase Free (Postgres) — RECOMMANDÉ
   ✓ Offre gratuite la plus large (500 Mo de DB + 5 Go de bande passante, requêtes illimitées)
   ✓ Postgres = requêtes SQL puissantes, interface Supabase Studio pour visualiser les données
   ✓ TypeScript typé généré automatiquement
   ✓ Configuration en 5 minutes (Console + coller 2 variables d'environnement)
   ⚠ Les projets gratuits se mettent en pause après 7 jours d'inactivité → je configure un ping cron Vercel vers `/api/health` toutes les 6 jours pour résoudre ce problème
   ⚠ TTL manuel via pg_cron (déjà configuré dans la migration SQL)
   → Adapté pour < 2000 commandes/mois, facile à étendre avec des fonctionnalités d'administration

Choisissez 1 ou 2 ?

POINT DE CONTRÔLE : NE PAS passer à la Phase 1 tant que l'utilisateur n'a pas choisi. Suggérer Supabase par défaut mais forcer un choix explicite.

Après que l'utilisateur a choisi, résumer le plan :

Vous avez choisi [Vercel KV / Supabase]. Je vais :

1. Vous guider pour configurer le compte Sepay (5-10 minutes)
2. Configurer le stockage de leads selon le fournisseur choisi
3. Connecter le code : lib/leads-store.ts + /api/checkout + /api/sepay-webhook + intégration VietQR
4. Tester

Prêt à passer à la Phase 1 ?

---

Phase 1 — Guider l'utilisateur pour configurer le compte Sepay

Consulter references/sepay-account-setup.md pour le guide complet. Résumé en 5 étapes pour l'utilisateur :

Étape 1 — S'inscrire sur my.sepay.vn

1. Aller sur https://my.sepay.vn → S'inscrire
2. Remplir le numéro de téléphone, l'email, le mot de passe → vérifier OTP
3. Compléter le profil : Nom complet + CCCD/CMND (individu) ou code fiscal (entreprise)

Étape 2 — Lier le compte bancaire

Tableau de bord → Comptes bancaires → Ajouter un compte :

• Choisir la banque (Vietcombank, Techcombank, MB, ACB, VPBank, BIDV, VietinBank, TPBank, ...)
• Saisir le numéro de compte + nom du titulaire (correspondant à l'application bancaire)
• Vérification automatique (via API bancaire) ou manuelle (virement de 1 000 à 10 000 VND avec le code de vérification fourni par Sepay)

Étape 3 — Obtenir la clé API

Tableau de bord → Paramètres → API & Webhook → Créer une nouvelle clé API :

• Nom : landing-page-prod
• Permissions : webhook:read
• Copier la clé (affichée une seule fois)

Étape 4 — Configurer l'URL du webhook

Même page → Webhook → Ajouter un webhook :

• URL : https://yourdomain.vn/api/sepay-webhook (sera en ligne après le déploiement)
• Authentification : API Key → coller la clé que vous venez de créer
• Événements : transaction:incoming
• Enregistrer

⚠️ Développement local : utiliser ngrok pour exposer localhost:3000 et tester avec Sepay.

Étape 5 — Coller les informations pour le skill

SEPAY_WEBHOOK_API_KEY=sk_xxxxxxxxxxxxxxxxxxxx
SEPAY_BANK_ACCOUNT_NUMBER=1023456789
SEPAY_BANK_NAME=Vietcombank
SEPAY_ACCOUNT_NAME=NGUYEN VAN A

POINT DE CONTRÔLE : NE PAS passer à la Phase 2 tant que l'utilisateur n'a pas collé toutes les informations.

---

Phase 2A — Configurer Vercel KV (uniquement si l'utilisateur a choisi KV à la Phase 0)

Vercel KV = Upstash Redis géré. Gratuit : 30 000 commandes/mois.

2A.1 Créer un namespace KV

Tableau de bord Vercel → Projet → Stockage → Créer une base de données → KV (Redis) → nom sepay-leads → Créer.

Génère automatiquement 4 variables d'environnement :

KV_URL=...
KV_REST_API_URL=...
KV_REST_API_TOKEN=...
KV_REST_API_READ_ONLY_TOKEN=...

Cliquez sur Connecter au projet → Vercel injecte les variables d'environnement (Production + Preview + Development).

2A.2 Récupérer les variables d'environnement en local

npm i -g vercel    # si pas déjà installé
vercel link
vercel env pull .env.local

2A.3 Installer le package

pnpm add @vercel/kv  # ou yarn / npm install

2A.4 Vérifier

node -e "
const { kv } = require('@vercel/kv');
kv.set('test', 'hello').then(() => kv.get('test')).then(v => {
  console.log('KV OK:', v);
  return kv.del('test');
});
"

Attendu KV OK: hello. Passer à la Phase 3.

---

Phase 2B — Configurer Supabase Free (uniquement si l'utilisateur a choisi Supabase à la Phase 0)

Consulter references/supabase-setup.md pour le guide complet en 6 étapes. Résumé :

2B.1 Créer un compte et un projet Supabase

1. https://supabase.com → Démarrer votre projet → Connexion GitHub
2. Nouveau projet :
   • Nom : sepay-leads-<marque>
   • Mot de passe de la base de données : cliquer sur Générer → sauvegarder
   • Région : ⚠️ Asie du Sud-Est (Singapour) (us-east par défaut a une latence de 250 ms+)
   • Forfait : Gratuit
3. Attendre ~2 minutes le provisionnement

2B.2 Exécuter la migration SQL

Barre latérale → Éditeur SQL → Nouvelle requête → coller le contenu de templates/supabase-migration.sql → Exécuter.

Crée 4 tables + index + fonction next_order_id() + activation RLS + tâche de nettoyage quotidien pg_cron.

Vérifier la sortie : 4 tables (leads/phone_index/order_counter/webhook_dedup) + 1 tâche pg_cron + next_order_id() retourne "DH000001".

Réinitialiser le compteur (car la vérification l'a incrémenté) :

UPDATE order_counter SET current_value = 0 WHERE id = 1;
DELETE FROM leads WHERE order_id = 'DH000001';

2B.3 Récupérer les identifiants API

Paramètres du projet → API :

• Copier l'URL du projet (https://xxxxx.supabase.co)
• Copier le secret service_role (PAS la clé anon — service_role contourne RLS, utilisée côté serveur)

2B.4 Coller les variables d'environnement

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJI...

Vérification automatique par le skill :

• URL correspond à ^https://[a-z0-9]+\.supabase\.co$
• La clé décode le JWT, vérifie role: "service_role" (PAS anon)

Si erreur → signaler l'erreur, demander de ressaisir.

2B.5 Installer le package

pnpm add @supabase/supabase-js

2B.6 Configurer le ping cron Vercel (empêcher la mise en pause)

Les projets Supabase Free se mettent en pause après 7 jours d'inactivité. Solution de contournement : ping /api/health toutes les 6 jours.

Le skill crée app/api/health/route.ts (à partir de templates/api-health-route.ts) + ajoute vercel.json avec :

{
  "crons": [
    { "path": "/api/health", "schedule": "0 3 */6 * *" }
  ]
}

⚠️ Vercel Cron Hobby est limité à 2 cron/mois. Le modèle */6 days = ~5 fois/mois → dépasse le quota. Options :

1. Vercel Pro (20 $/mois) — cron illimité
2. Workflow GitHub Actions .github/workflows/keep-alive.yml (GRATUIT) — le skill le crée s'il détecte un dépôt GitHub
3. cron-job.org (GRATUIT) — configuration manuelle, coller l'URL /api/health

Par défaut, le skill choisit l'option 2 (GitHub Actions) si le repo a .git/config avec un remote GitHub. Sinon, il affiche les instructions de l'option 3.

2B.7 Vérifier

node -e "
const { createClient } = require('@supabase/supabase-js');
const sb = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_ROLE_KEY);
sb.from('order_counter').select('current_value').eq('id', 1).single().then(r => {
  if (r.error) { console.error('ÉCHEC :', r.error.message); process.exit(1); }
  console.log('Supabase OK. current_value =', r.data.current_value);
});
"

Attendu Supabase OK. current_value = 0. Passer à la Phase 3.

---

Phase 3 — Créer lib/leads-store.ts + implémentation

Abstraction du fournisseur : les routes API importent depuis lib/leads-store.ts, ignorant si le stockage sous-jacent est KV ou Postgres.

Si KV est choisi (Phase 0)

Créer 2 fichiers :

• lib/leads-store.ts ← copie de templates/lib-leads-store-kv.ts (1 ligne export * from './leads-kv')
• lib/leads-kv.ts ← copie de templates/lib-leads-kv.ts (implémentation KV, ~160 lignes)

Si Supabase est choisi

Créer 3 fichiers :

• lib/leads-store.ts ← copie de templates/lib-leads-store-supabase.ts (réexportation Supabase)
• lib/leads-supabase.ts ← copie de templates/lib-leads-supabase.ts (implémentation Postgres + listLeads pour l'admin)
• lib/supabase-admin.ts ← copie de templates/lib-supabase-admin.ts (client admin mis en cache singleton avec service_role)

SURFACE DE L'API COMMUNE (les deux implémentations) :

• createLead(input) → { orderId, lead } — ID atomique + insertion + index secondaire
• getLeadByOrderId(orderId) → Lead | null
• getLeadByPhone(phone) → Lead | null — recherche de secours
• findPendingLeadByAmountAndTime(amount, start, end) → Lead[] — matching webhook Stratégie 3
• markLeadPaid(orderId, payment) → Lead | null
• isTransactionProcessed(sepayId) → boolean — déduplication
• markTransactionProcessed(sepayId) → void

TTL : 7 jours en attente / 90 jours payé. KV via paramètre ex: . Supabase via champ expire_at + tâche de nettoyage quotidien pg_cron.

Changer de fournisseur ultérieurement = modifier 1 ligne dans leads-store.ts (NE PAS toucher au code API).

Consulter references/leads-kv-schema.md (KV) ou references/supabase-leads-schema.md (Supabase) pour les justifications détaillées.

---

Phase 4 — Créer la route /api/checkout

Consulter templates/api-checkout-app-router.ts (App Router) ou templates/api-checkout-pages-router.ts (Pages Router). Copier dans le chemin correspondant.

Les deux templates utilisent import { createLead } from '@/lib/leads-store' — indépendant du fournisseur.

Flux :

Client POST /api/checkout { name, phone, email, productName, amount }
  ↓
Serveur :
  1. Valider (format téléphone VN, regex email, montant > 0)
  2. createLead() → { orderId: "DH000123" }
  3. Générer l'URL du QR Sepay : https://qr.sepay.vn/img?acc=X&bank=Y&amount=Z&des=DH000123&template=compact
  4. Retourner { orderId, amount, bankInfo, content, qrUrl }
  ↓
Client : afficher la modale QR OU rediriger vers /checkout/DH000123

---

Phase 5 — Créer la route /api/sepay-webhook

Consulter templates/api-sepay-webhook-app-router.ts. Copier dans app/api/sepay-webhook/route.ts.

Le template utilise import ... from '@/lib/leads-store' — indépendant du fournisseur.

Flux :

Sepay POST /api/sepay-webhook
  Authorization: Apikey {SEPAY_WEBHOOK_API_KEY}
  Corps : SepayWebhookPayload
  ↓
Serveur :
  1. Vérifier l'authentification via timingSafeEqual — protection contre les attaques temporelles
  2. Déduplication précoce : isTransactionProcessed(payload.id) → retourner 200 rapidement
  3. Enregistrer la déduplication EN PREMIER — idempotent même en cas d'échec du traitement
  4. Filtrer transferType === 'in' (ignorer les sorties)
  5. Matching multi-stratégie :
     a. contenu → order_id (regex /DH\d+/)
     b. contenu → téléphone (regex /0\d{9}/) → getLeadByPhone
     c. montant + timestamp ±30min → findPendingLeadByAmountAndTime (accepter uniquement si longueur === 1)
  6. Rejeter les sous-paiements, ACCEPTER les trop-payés
  7. markLeadPaid(orderId, payment) → mettre à jour le stockage
  8. Diffuser les effets de bord via boucle try/catch (PAS Promise.all)
  9. TOUJOURS retourner 200 (même en cas d'erreur interne) — Sepay réessaie avec Fibonacci 7 fois si non-200

Espace réservé pour les effets de bord qui seront connectés ultérieurement par biz-email-setup et biz-telegram-payment-notify.

Consulter references/sepay-webhook-flow.md pour les justifications de la déduplication et le comportement de réessai.

---

Phase 6 — Intégrer VietQR dans la landing page

3 modèles UX, demander à l'utilisateur de choisir 1 :

Modèle	Quand	UX
A. Popup modale	Produit unique / achat impulsif	Soumettre le formulaire → popup QR directement sur la page d'origine
B. Page /checkout/[orderId]	Produits multiples / nécessité de partager l'URL ... (suite tronquée)