940 lines
29 KiB
Markdown
940 lines
29 KiB
Markdown
# SePay Best Practices
|
|
|
|
Production-proven patterns for Vietnamese bank transfer payments via SePay/VietQR, covering transaction parsing, webhook handling, order matching, currency conversion, and error handling.
|
|
|
|
## Environment Configuration
|
|
|
|
### Required Environment Variables
|
|
```bash
|
|
# Core API
|
|
SEPAY_API_TOKEN=xxx # Bearer token for SePay API
|
|
SEPAY_WEBHOOK_API_KEY=xxx # API key for webhook authentication
|
|
SEPAY_API_URL=https://my.sepay.vn/userapi # Base URL (optional)
|
|
|
|
# Bank Account Details
|
|
SEPAY_ACCOUNT_NUMBER=0123456789 # Bank account for transfers
|
|
SEPAY_ACCOUNT_NAME=COMPANY_NAME # Account holder name
|
|
SEPAY_BANK_NAME=Vietcombank # Bank name (VietQR recognized)
|
|
```
|
|
|
|
### Product Pricing in VND
|
|
```typescript
|
|
// lib/sepay.ts
|
|
const VND_PRICES = {
|
|
engineer_kit: 2450000, // ~$100 USD
|
|
marketing_kit: 2450000, // ~$100 USD
|
|
combo: 3650000, // ~$149 USD
|
|
} as const;
|
|
|
|
const USD_TO_VND_RATE = 24500; // 1 USD ≈ 24,500 VND
|
|
```
|
|
|
|
## Transaction Content Format
|
|
|
|
### Standard Format
|
|
```
|
|
CLAUDEKIT {order-uuid}
|
|
```
|
|
Example: `CLAUDEKIT 4e4635f4-0478-4080-a5c5-48da91f97f1e`
|
|
|
|
### Team Checkout Format
|
|
```
|
|
TEAM{8-hex-chars}
|
|
```
|
|
Example: `TEAM4E4635F4`
|
|
|
|
### Why These Formats
|
|
- UUID ensures global uniqueness
|
|
- `CLAUDEKIT` prefix for easy visual identification
|
|
- Short team prefix fits bank memo limits
|
|
- Case-insensitive matching handles bank transformations
|
|
|
|
## QR Code Generation
|
|
|
|
### VietQR URL Pattern
|
|
```typescript
|
|
// lib/sepay.ts
|
|
export function generateVietQRUrl(
|
|
accountNumber: string,
|
|
bankName: string,
|
|
amount: number,
|
|
content: string
|
|
): string {
|
|
const params = new URLSearchParams({
|
|
acc: accountNumber,
|
|
bank: bankName,
|
|
amount: String(Math.floor(amount)), // Integer only
|
|
des: content,
|
|
});
|
|
|
|
return `https://qr.sepay.vn/img?${params.toString()}`;
|
|
}
|
|
```
|
|
|
|
### Usage Example
|
|
```typescript
|
|
const qrUrl = generateVietQRUrl(
|
|
process.env.SEPAY_ACCOUNT_NUMBER!,
|
|
process.env.SEPAY_BANK_NAME!,
|
|
2450000,
|
|
`CLAUDEKIT ${orderId}`
|
|
);
|
|
// Returns: https://qr.sepay.vn/img?acc=0123456789&bank=Vietcombank&amount=2450000&des=CLAUDEKIT+uuid
|
|
```
|
|
|
|
## Checkout API Implementation
|
|
|
|
### Standard SePay Checkout
|
|
```typescript
|
|
// app/api/checkout/sepay/route.ts
|
|
import { NextResponse } from 'next/server';
|
|
import { z } from 'zod';
|
|
|
|
const checkoutSchema = z.object({
|
|
email: z.string().email(),
|
|
name: z.string().optional(),
|
|
productType: z.enum(['engineer_kit', 'marketing_kit', 'combo']),
|
|
githubUsername: z.string().min(1),
|
|
couponCode: z.string().optional(),
|
|
vatInvoiceRequested: z.boolean().optional(),
|
|
taxId: z.string().regex(/^\d{10}$|^\d{13}$/).optional(), // 10 or 13 digits
|
|
});
|
|
|
|
export async function POST(request: Request) {
|
|
try {
|
|
const body = await request.json();
|
|
const data = checkoutSchema.parse(body);
|
|
|
|
// 1. Normalize email
|
|
const normalizedEmail = data.email.toLowerCase().trim();
|
|
|
|
// 2. Get base price
|
|
const originalAmount = VND_PRICES[data.productType];
|
|
let finalAmount = originalAmount;
|
|
let discountMetadata: Record<string, any> = { originalAmount };
|
|
|
|
// 3. CRITICAL: Apply discounts in correct order
|
|
// Step A: Apply coupon FIRST
|
|
if (data.couponCode) {
|
|
const couponResult = await validateCouponForVND(data.couponCode, originalAmount);
|
|
if (couponResult.valid) {
|
|
finalAmount = originalAmount - couponResult.discountAmountVND;
|
|
discountMetadata.couponCode = data.couponCode;
|
|
discountMetadata.couponDiscountAmount = couponResult.discountAmountVND;
|
|
discountMetadata.couponId = couponResult.couponId;
|
|
}
|
|
}
|
|
|
|
// Step B: Apply referral SECOND (on post-coupon amount)
|
|
const referralCode = getReferralCodeFromCookie(request);
|
|
if (referralCode) {
|
|
const referralResult = await calculateReferralDiscountVND(
|
|
referralCode,
|
|
finalAmount, // Post-coupon amount
|
|
normalizedEmail
|
|
);
|
|
if (referralResult.valid && referralResult.discountAmount > 0) {
|
|
// Validate calculation
|
|
if (referralResult.discountAmount <= 0) {
|
|
return NextResponse.json(
|
|
{ error: 'Invalid discount calculation' },
|
|
{ status: 400 }
|
|
);
|
|
}
|
|
finalAmount -= referralResult.discountAmount;
|
|
discountMetadata.referralCode = referralCode;
|
|
discountMetadata.referralDiscountAmount = referralResult.discountAmount;
|
|
discountMetadata.referrerId = referralResult.referrerId;
|
|
}
|
|
}
|
|
|
|
// 4. Validate final amount
|
|
if (finalAmount <= 0) {
|
|
return NextResponse.json(
|
|
{ error: 'Invalid final amount' },
|
|
{ status: 400 }
|
|
);
|
|
}
|
|
|
|
// 5. Encrypt sensitive data if VAT invoice requested
|
|
let encryptedTaxId: string | null = null;
|
|
if (data.vatInvoiceRequested && data.taxId) {
|
|
encryptedTaxId = await encrypt(data.taxId);
|
|
}
|
|
|
|
// 6. Create order record
|
|
const orderId = crypto.randomUUID();
|
|
const transactionContent = `CLAUDEKIT ${orderId}`;
|
|
|
|
const order = await db.insert(orders).values({
|
|
id: orderId,
|
|
email: normalizedEmail,
|
|
productType: data.productType,
|
|
amount: finalAmount,
|
|
currency: 'VND',
|
|
status: 'pending',
|
|
paymentProvider: 'sepay',
|
|
paymentId: transactionContent, // Used for matching
|
|
referredBy: discountMetadata.referrerId,
|
|
discountAmount: originalAmount - finalAmount,
|
|
metadata: JSON.stringify({
|
|
...discountMetadata,
|
|
githubUsername: data.githubUsername,
|
|
vatInvoiceRequested: data.vatInvoiceRequested,
|
|
encryptedTaxId,
|
|
}),
|
|
}).returning();
|
|
|
|
// 7. Generate payment instructions
|
|
const qrCode = generateVietQRUrl(
|
|
process.env.SEPAY_ACCOUNT_NUMBER!,
|
|
process.env.SEPAY_BANK_NAME!,
|
|
finalAmount,
|
|
transactionContent
|
|
);
|
|
|
|
return NextResponse.json({
|
|
orderId: order[0].id,
|
|
paymentMethod: 'bank_transfer',
|
|
payment: {
|
|
bankName: process.env.SEPAY_BANK_NAME,
|
|
accountNumber: process.env.SEPAY_ACCOUNT_NUMBER,
|
|
accountName: process.env.SEPAY_ACCOUNT_NAME,
|
|
amount: finalAmount,
|
|
currency: 'VND',
|
|
content: transactionContent,
|
|
qrCode,
|
|
instructions: [
|
|
'Open your banking app',
|
|
'Scan the QR code or transfer manually',
|
|
'Use the exact transfer content shown',
|
|
'Payment will be confirmed automatically',
|
|
],
|
|
},
|
|
statusCheckUrl: `/api/orders/${order[0].id}/status`,
|
|
});
|
|
|
|
} catch (error) {
|
|
if (error instanceof z.ZodError) {
|
|
return NextResponse.json({ error: error.errors }, { status: 400 });
|
|
}
|
|
console.error('SePay checkout error:', error);
|
|
return NextResponse.json(
|
|
{ error: 'Failed to create checkout' },
|
|
{ status: 500 }
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
## Webhook Handling
|
|
|
|
### Webhook Authentication (Timing-Safe)
|
|
```typescript
|
|
// app/api/webhooks/sepay/route.ts
|
|
import { timingSafeEqual } from 'crypto';
|
|
import { NextResponse } from 'next/server';
|
|
|
|
function verifyWebhookAuth(request: Request): boolean {
|
|
const authHeader = request.headers.get('Authorization');
|
|
if (!authHeader) return false;
|
|
|
|
const expectedKey = process.env.SEPAY_WEBHOOK_API_KEY!;
|
|
|
|
// Support both "Bearer" and "Apikey" formats
|
|
let providedKey: string;
|
|
if (authHeader.startsWith('Bearer ')) {
|
|
providedKey = authHeader.slice(7);
|
|
} else if (authHeader.startsWith('Apikey ')) {
|
|
providedKey = authHeader.slice(7);
|
|
} else {
|
|
return false;
|
|
}
|
|
|
|
// Timing-safe comparison to prevent timing attacks
|
|
try {
|
|
const expected = Buffer.from(expectedKey);
|
|
const provided = Buffer.from(providedKey);
|
|
if (expected.length !== provided.length) return false;
|
|
return timingSafeEqual(expected, provided);
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
export async function POST(request: Request) {
|
|
// 1. Verify authentication
|
|
if (!verifyWebhookAuth(request)) {
|
|
return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
|
|
}
|
|
|
|
const payload = await request.json();
|
|
|
|
// 2. Extract event ID for idempotency
|
|
const eventId = String(payload.id || payload.transaction_id || Date.now());
|
|
|
|
// 3. Check for duplicate
|
|
const existingEvent = await db.select()
|
|
.from(webhookEvents)
|
|
.where(eq(webhookEvents.eventId, eventId))
|
|
.limit(1);
|
|
|
|
if (existingEvent.length > 0) {
|
|
console.log(`Duplicate SePay webhook ignored: ${eventId}`);
|
|
return NextResponse.json({ success: true });
|
|
}
|
|
|
|
// 4. Record event BEFORE processing (idempotency)
|
|
await db.insert(webhookEvents).values({
|
|
id: crypto.randomUUID(),
|
|
provider: 'sepay',
|
|
eventType: 'transaction',
|
|
eventId,
|
|
payload: JSON.stringify(payload),
|
|
processed: false,
|
|
});
|
|
|
|
try {
|
|
await processTransaction(payload);
|
|
|
|
await db.update(webhookEvents)
|
|
.set({ processed: true, processedAt: new Date() })
|
|
.where(eq(webhookEvents.eventId, eventId));
|
|
|
|
} catch (error) {
|
|
// Log error but return 200 to prevent retry loop
|
|
await db.update(webhookEvents)
|
|
.set({
|
|
processed: true,
|
|
processedAt: new Date(),
|
|
error: error instanceof Error ? error.message : 'Unknown error',
|
|
})
|
|
.where(eq(webhookEvents.eventId, eventId));
|
|
}
|
|
|
|
// Always return 200 to prevent SePay retries
|
|
return NextResponse.json({ success: true });
|
|
}
|
|
```
|
|
|
|
### Webhook Payload Structure
|
|
```typescript
|
|
interface SepayWebhookPayload {
|
|
id: number; // Transaction ID (unique key)
|
|
gateway: string; // Bank name (e.g., "Vietcombank")
|
|
transactionDate: string; // "2025-01-07 10:30:00"
|
|
accountNumber: string; // Account number
|
|
code?: string; // Optional payment code
|
|
content: string; // Transaction memo - CRITICAL for matching
|
|
transferType: 'in' | 'out'; // Only process 'in'
|
|
transferAmount: number; // Amount in VND
|
|
accumulated: number; // Balance after transaction
|
|
subAccount?: string;
|
|
referenceCode?: string;
|
|
description?: string;
|
|
}
|
|
```
|
|
|
|
## Order Matching Strategy
|
|
|
|
### Multi-Strategy Fallback Chain
|
|
```typescript
|
|
// lib/sepay.ts
|
|
export async function findOrderByTransaction(
|
|
payload: SepayWebhookPayload
|
|
): Promise<{ order: Order | null; matchMethod: string }> {
|
|
const { content, transferAmount, transactionDate } = payload;
|
|
|
|
// Strategy 1: Parse Order ID from content (preferred)
|
|
const parsedOrderId = parseOrderIdFromContent(content);
|
|
if (parsedOrderId) {
|
|
const order = await db.select()
|
|
.from(orders)
|
|
.where(eq(orders.id, parsedOrderId))
|
|
.limit(1);
|
|
|
|
if (order[0]) {
|
|
return { order: order[0], matchMethod: 'content-parse' };
|
|
}
|
|
}
|
|
|
|
// Strategy 2: Team payment ID match
|
|
const teamMatch = content.match(/TEAM([A-F0-9]{8})/i);
|
|
if (teamMatch) {
|
|
const teamPaymentId = `TEAM${teamMatch[1].toUpperCase()}`;
|
|
const order = await db.select()
|
|
.from(orders)
|
|
.where(eq(orders.paymentId, teamPaymentId))
|
|
.limit(1);
|
|
|
|
if (order[0]) {
|
|
return { order: order[0], matchMethod: 'team-payment-id' };
|
|
}
|
|
}
|
|
|
|
// Strategy 3: Amount + timestamp window (±30 minutes)
|
|
const transactionTime = new Date(transactionDate);
|
|
const windowStart = new Date(transactionTime.getTime() - 30 * 60 * 1000);
|
|
const windowEnd = new Date(transactionTime.getTime() + 30 * 60 * 1000);
|
|
|
|
const windowMatches = await db.select()
|
|
.from(orders)
|
|
.where(and(
|
|
eq(orders.status, 'pending'),
|
|
eq(orders.paymentProvider, 'sepay'),
|
|
eq(orders.amount, transferAmount),
|
|
gte(orders.createdAt, windowStart),
|
|
lte(orders.createdAt, windowEnd)
|
|
))
|
|
.limit(10);
|
|
|
|
if (windowMatches.length === 1) {
|
|
return { order: windowMatches[0], matchMethod: 'timestamp-window' };
|
|
}
|
|
|
|
if (windowMatches.length > 1) {
|
|
// Multiple matches - select closest by creation time
|
|
const closest = windowMatches.reduce((prev, curr) => {
|
|
const prevDiff = Math.abs(prev.createdAt.getTime() - transactionTime.getTime());
|
|
const currDiff = Math.abs(curr.createdAt.getTime() - transactionTime.getTime());
|
|
return currDiff < prevDiff ? curr : prev;
|
|
});
|
|
return { order: closest, matchMethod: 'timestamp-window-closest' };
|
|
}
|
|
|
|
// Strategy 4: Amount only (last resort - single match only)
|
|
const amountMatches = await db.select()
|
|
.from(orders)
|
|
.where(and(
|
|
eq(orders.status, 'pending'),
|
|
eq(orders.paymentProvider, 'sepay'),
|
|
eq(orders.amount, transferAmount)
|
|
))
|
|
.limit(2);
|
|
|
|
if (amountMatches.length === 1) {
|
|
console.warn(`⚠️ Amount-only match for ${transferAmount} VND - verify manually`);
|
|
return { order: amountMatches[0], matchMethod: 'amount-only' };
|
|
}
|
|
|
|
// No match found
|
|
console.error(`❌ Could not match order:
|
|
Content: "${content}"
|
|
Amount: ${transferAmount} VND
|
|
Transaction Date: ${transactionDate}`);
|
|
|
|
return { order: null, matchMethod: 'none' };
|
|
}
|
|
```
|
|
|
|
### UUID Parsing with Bank Transformations
|
|
```typescript
|
|
// lib/sepay.ts
|
|
export function parseOrderIdFromContent(content: string): string | null {
|
|
if (!content) return null;
|
|
|
|
// Pattern 1: Standard "CLAUDEKIT {uuid}"
|
|
const claudekitMatch = content.match(/CLAUDEKIT\s+([\w-]+)/i);
|
|
if (claudekitMatch) {
|
|
return normalizeUUID(claudekitMatch[1]);
|
|
}
|
|
|
|
// Pattern 2: UUID anywhere in content (banks may strip/transform content)
|
|
// Match 8-4-4-4-12 hex with optional dashes
|
|
const uuidMatch = content.match(
|
|
/([0-9A-F]{8}-?[0-9A-F]{4}-?[0-9A-F]{4}-?[0-9A-F]{4}-?[0-9A-F]{12})/i
|
|
);
|
|
if (uuidMatch) {
|
|
return normalizeUUID(uuidMatch[1]);
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
function normalizeUUID(input: string): string | null {
|
|
// Remove dashes and validate
|
|
const cleaned = input.replace(/-/g, '');
|
|
|
|
if (cleaned.length !== 32) return null;
|
|
if (!/^[0-9a-f]+$/i.test(cleaned)) return null;
|
|
|
|
// Re-format to standard UUID format
|
|
return [
|
|
cleaned.slice(0, 8),
|
|
cleaned.slice(8, 12),
|
|
cleaned.slice(12, 16),
|
|
cleaned.slice(16, 20),
|
|
cleaned.slice(20),
|
|
].join('-').toLowerCase();
|
|
}
|
|
```
|
|
|
|
### Handled Content Formats
|
|
```
|
|
CLAUDEKIT 4e4635f4-0478-4080-a5c5-48da91f97f1e ✅ Standard
|
|
CLAUDEKIT 4e4635f404784080a5c548da91f97f1e ✅ Bank stripped dashes
|
|
CLAUDEKIT4e4635f404784080a5c548da91f97f1e ✅ No space
|
|
4e4635f404784080a5c548da91f97f1e-CLAUDEKIT ✅ Reversed
|
|
claudekit 4e4635f4-0478-4080-a5c5-48da91f97f1e ✅ Lowercase
|
|
BankAPINotify 4e4635f404784080a5c548da91f97f1e... ✅ Extra prefix
|
|
4e4635f404784080a5c548da91f97f1e ✅ UUID only
|
|
```
|
|
|
|
## Transaction Processing
|
|
|
|
### Complete Processing Flow
|
|
```typescript
|
|
async function processTransaction(payload: SepayWebhookPayload) {
|
|
// 1. Only process incoming transfers
|
|
if (payload.transferType !== 'in') {
|
|
console.log('Skipping outbound transfer');
|
|
return;
|
|
}
|
|
|
|
// 2. Find matching order
|
|
const { order, matchMethod } = await findOrderByTransaction(payload);
|
|
if (!order) {
|
|
console.error('No matching order found');
|
|
return;
|
|
}
|
|
|
|
// 3. Verify amount (allow overpayment)
|
|
if (payload.transferAmount < order.amount) {
|
|
console.error(`Underpayment: expected ${order.amount}, got ${payload.transferAmount}`);
|
|
return;
|
|
}
|
|
if (payload.transferAmount > order.amount) {
|
|
console.log(`Overpayment accepted: expected ${order.amount}, got ${payload.transferAmount}`);
|
|
}
|
|
|
|
// 4. Update order with transaction details
|
|
const existingMetadata = order.metadata ? JSON.parse(order.metadata) : {};
|
|
await db.update(orders)
|
|
.set({
|
|
status: 'completed',
|
|
paymentId: String(payload.id),
|
|
metadata: JSON.stringify({
|
|
...existingMetadata, // Preserve discount info
|
|
gateway: payload.gateway,
|
|
transactionDate: payload.transactionDate,
|
|
accountNumber: payload.accountNumber,
|
|
transferAmount: payload.transferAmount,
|
|
content: payload.content,
|
|
matchMethod,
|
|
transactionId: payload.id,
|
|
}),
|
|
updatedAt: new Date(),
|
|
})
|
|
.where(eq(orders.id, order.id));
|
|
|
|
// 5. Create license (non-blocking)
|
|
try {
|
|
await createLicense(order);
|
|
} catch (error) {
|
|
console.error('Failed to create license:', error);
|
|
}
|
|
|
|
// 6. Send confirmation email (non-blocking)
|
|
try {
|
|
await sendOrderConfirmation(order, payload);
|
|
} catch (error) {
|
|
console.error('Failed to send confirmation:', error);
|
|
}
|
|
|
|
// 7. Create referral commission (non-blocking)
|
|
if (order.referredBy) {
|
|
try {
|
|
// Commission based on actual paid amount
|
|
await createCommission({
|
|
orderId: order.id,
|
|
referrerId: order.referredBy,
|
|
baseAmount: payload.transferAmount, // Actual paid amount
|
|
currency: 'VND',
|
|
});
|
|
} catch (error) {
|
|
console.error('Failed to create commission:', error);
|
|
}
|
|
}
|
|
|
|
// 8. Update referrer tier (non-blocking)
|
|
if (order.referredBy) {
|
|
try {
|
|
const usdConversion = await convertVndToUsd(payload.transferAmount);
|
|
await updateReferrerTier(order.referredBy, usdConversion.usdCents, order.id);
|
|
} catch (error) {
|
|
console.error('Failed to update tier:', error);
|
|
}
|
|
}
|
|
|
|
// 9. Grant GitHub access (non-blocking)
|
|
try {
|
|
const metadata = JSON.parse(order.metadata || '{}');
|
|
await inviteToGitHub(metadata.githubUsername, order.productType);
|
|
} catch (error) {
|
|
console.error('Failed to invite to GitHub:', error);
|
|
}
|
|
|
|
// 10. Sync Polar discount redemption (non-blocking)
|
|
const metadata = JSON.parse(order.metadata || '{}');
|
|
if (metadata.couponId && metadata.couponCode) {
|
|
try {
|
|
await syncPolarDiscountWithRetry(order.id, metadata.couponId, metadata.couponCode);
|
|
} catch (error) {
|
|
console.error('Failed to sync Polar discount:', error);
|
|
await sendDiscordAlert('Polar discount sync failed', { orderId: order.id });
|
|
}
|
|
}
|
|
|
|
// 11. Send sales notification (non-blocking)
|
|
try {
|
|
await sendSalesNotification({
|
|
...order,
|
|
gateway: payload.gateway,
|
|
transactionId: payload.id,
|
|
});
|
|
} catch (error) {
|
|
console.error('Failed to send Discord notification:', error);
|
|
}
|
|
}
|
|
```
|
|
|
|
## Currency Conversion
|
|
|
|
### VND to USD with Multi-Layer Fallback
|
|
```typescript
|
|
// lib/currency.ts
|
|
const EXCHANGE_RATE_CACHE_TTL = 60 * 60 * 1000; // 1 hour
|
|
const FALLBACK_VND_TO_USD = 24500; // Conservative fallback
|
|
|
|
let exchangeRateCache: {
|
|
rate: number;
|
|
timestamp: number;
|
|
source: 'api' | 'cached' | 'expired' | 'fallback';
|
|
} | null = null;
|
|
|
|
export async function convertVndToUsd(vndAmount: number): Promise<{
|
|
usdCents: number;
|
|
rate: number;
|
|
source: string;
|
|
}> {
|
|
const now = Date.now();
|
|
|
|
// Layer 1: Fresh cache
|
|
if (exchangeRateCache && now - exchangeRateCache.timestamp < EXCHANGE_RATE_CACHE_TTL) {
|
|
const usdCents = Math.round((vndAmount / exchangeRateCache.rate) * 100);
|
|
return { usdCents, rate: exchangeRateCache.rate, source: 'cached' };
|
|
}
|
|
|
|
// Layer 2: Try live API
|
|
try {
|
|
const response = await fetch(
|
|
'https://api.exchangerate-api.com/v4/latest/USD',
|
|
{ signal: AbortSignal.timeout(5000) }
|
|
);
|
|
const data = await response.json();
|
|
const rate = data.rates.VND;
|
|
|
|
exchangeRateCache = { rate, timestamp: now, source: 'api' };
|
|
const usdCents = Math.round((vndAmount / rate) * 100);
|
|
return { usdCents, rate, source: 'api' };
|
|
|
|
} catch (error) {
|
|
console.warn('Exchange rate API failed:', error);
|
|
|
|
// Layer 3: Expired cache (better than nothing)
|
|
if (exchangeRateCache) {
|
|
const usdCents = Math.round((vndAmount / exchangeRateCache.rate) * 100);
|
|
return { usdCents, rate: exchangeRateCache.rate, source: 'expired_cache' };
|
|
}
|
|
|
|
// Layer 4: Hardcoded fallback
|
|
const usdCents = Math.round((vndAmount / FALLBACK_VND_TO_USD) * 100);
|
|
return { usdCents, rate: FALLBACK_VND_TO_USD, source: 'fallback' };
|
|
}
|
|
}
|
|
```
|
|
|
|
### USD Discount to VND
|
|
```typescript
|
|
// When Polar discount is in USD, convert to VND for SePay checkout
|
|
export function convertUsdDiscountToVnd(
|
|
discount: { type: 'fixed' | 'percentage'; amount?: number; basisPoints?: number },
|
|
amountVND: number
|
|
): number {
|
|
if (discount.type === 'percentage') {
|
|
// Basis points: 1000 = 10%, 10000 = 100%
|
|
const percentage = (discount.basisPoints || 0) / 10000;
|
|
return Math.round(amountVND * percentage);
|
|
} else {
|
|
// Fixed amount in USD cents → VND
|
|
const usdDollars = (discount.amount || 0) / 100;
|
|
return Math.round(usdDollars * 24500); // Use conservative rate
|
|
}
|
|
}
|
|
```
|
|
|
|
## Invoice Email Template
|
|
|
|
### HTML Invoice Generation
|
|
```typescript
|
|
// lib/emails/sepay-invoice.ts
|
|
export function generateSepayInvoice(order: Order, transaction: TransactionInfo): string {
|
|
const metadata = JSON.parse(order.metadata || '{}');
|
|
const invoiceNumber = `INV-${format(new Date(), 'yyyyMMdd')}-${order.id.slice(-8).toUpperCase()}`;
|
|
|
|
// Format VND with Vietnamese locale
|
|
const formatVND = (amount: number) =>
|
|
new Intl.NumberFormat('vi-VN', { style: 'currency', currency: 'VND' }).format(amount);
|
|
|
|
// Escape HTML to prevent XSS
|
|
const escapeHtml = (text: string) =>
|
|
text.replace(/[&<>"']/g, char => ({
|
|
'&': '&',
|
|
'<': '<',
|
|
'>': '>',
|
|
'"': '"',
|
|
"'": ''',
|
|
})[char] || char);
|
|
|
|
return `
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<style>
|
|
.invoice { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; }
|
|
.header { background: linear-gradient(135deg, #ff6b6b, #feca57); padding: 20px; }
|
|
.status { background: #10b981; color: white; padding: 4px 12px; border-radius: 4px; }
|
|
.amount { font-size: 24px; font-weight: bold; }
|
|
.savings { color: #10b981; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="invoice">
|
|
<div class="header">
|
|
<h1>Invoice</h1>
|
|
<span class="status">PAID</span>
|
|
</div>
|
|
|
|
<table>
|
|
<tr><td>Invoice #:</td><td>${invoiceNumber}</td></tr>
|
|
<tr><td>Customer:</td><td>${escapeHtml(metadata.name || order.email)}</td></tr>
|
|
<tr><td>Email:</td><td>${escapeHtml(order.email)}</td></tr>
|
|
<tr><td>Payment Date:</td><td>${format(new Date(transaction.transactionDate), 'dd/MM/yyyy HH:mm')}</td></tr>
|
|
<tr><td>Transaction Ref:</td><td>${transaction.transactionId || 'N/A'}</td></tr>
|
|
</table>
|
|
|
|
<h3>Order Details</h3>
|
|
<table>
|
|
<tr><td>Product:</td><td>${getProductName(order.productType)}</td></tr>
|
|
<tr><td>Original Price:</td><td>${formatVND(metadata.originalAmount || order.amount)}</td></tr>
|
|
${metadata.couponDiscountAmount ? `
|
|
<tr><td>Coupon (${metadata.couponCode}):</td><td>-${formatVND(metadata.couponDiscountAmount)}</td></tr>
|
|
` : ''}
|
|
${metadata.referralDiscountAmount ? `
|
|
<tr><td>Referral Discount (20%):</td><td>-${formatVND(metadata.referralDiscountAmount)}</td></tr>
|
|
` : ''}
|
|
${order.discountAmount > 0 ? `
|
|
<tr class="savings"><td>Total Savings:</td><td>-${formatVND(order.discountAmount)}</td></tr>
|
|
` : ''}
|
|
<tr class="amount"><td>Total Paid:</td><td>${formatVND(order.amount)}</td></tr>
|
|
</table>
|
|
|
|
<p>Thank you for your purchase!</p>
|
|
<p>Support: support@claudekit.com</p>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
`;
|
|
}
|
|
```
|
|
|
|
## Error Handling Patterns
|
|
|
|
### Always Return 200 to SePay
|
|
```typescript
|
|
// Webhook must always return 200 to prevent retry loop
|
|
export async function POST(request: Request) {
|
|
try {
|
|
// ... processing
|
|
} catch (error) {
|
|
// Log error but don't fail
|
|
console.error('Webhook processing error:', error);
|
|
await logWebhookError(error);
|
|
}
|
|
|
|
// ALWAYS return 200
|
|
return NextResponse.json({ success: true });
|
|
}
|
|
```
|
|
|
|
### Non-Blocking Post-Payment Operations
|
|
```typescript
|
|
// Wrap each operation in try-catch
|
|
const operations = [
|
|
{ name: 'License', fn: () => createLicense(order) },
|
|
{ name: 'Email', fn: () => sendOrderConfirmation(order) },
|
|
{ name: 'Commission', fn: () => createCommission(order) },
|
|
{ name: 'GitHub', fn: () => inviteToGitHub(username, productType) },
|
|
{ name: 'Discord', fn: () => sendSalesNotification(order) },
|
|
];
|
|
|
|
for (const op of operations) {
|
|
try {
|
|
await op.fn();
|
|
console.log(`✅ ${op.name} completed`);
|
|
} catch (error) {
|
|
console.error(`❌ ${op.name} failed:`, error);
|
|
// Continue - don't block other operations
|
|
}
|
|
}
|
|
```
|
|
|
|
### Amount Validation
|
|
```typescript
|
|
// Reject underpayment, accept overpayment
|
|
if (transferAmount < order.amount) {
|
|
console.error(`Underpayment: expected ${order.amount}, received ${transferAmount}`);
|
|
await flagOrderForReview(order.id, 'underpayment');
|
|
return; // Don't process
|
|
}
|
|
|
|
if (transferAmount > order.amount) {
|
|
console.log(`Overpayment: expected ${order.amount}, received ${transferAmount}`);
|
|
// Continue processing - customer paid more than required
|
|
}
|
|
```
|
|
|
|
## Testing Patterns
|
|
|
|
### Unit Tests for UUID Parsing
|
|
```typescript
|
|
// __tests__/lib/sepay.test.ts
|
|
describe('parseOrderIdFromContent', () => {
|
|
it('parses standard format', () => {
|
|
expect(parseOrderIdFromContent('CLAUDEKIT 4e4635f4-0478-4080-a5c5-48da91f97f1e'))
|
|
.toBe('4e4635f4-0478-4080-a5c5-48da91f97f1e');
|
|
});
|
|
|
|
it('handles bank dash-stripping', () => {
|
|
expect(parseOrderIdFromContent('CLAUDEKIT 4e4635f404784080a5c548da91f97f1e'))
|
|
.toBe('4e4635f4-0478-4080-a5c5-48da91f97f1e');
|
|
});
|
|
|
|
it('handles real-world Vietnamese bank memo', () => {
|
|
expect(parseOrderIdFromContent('BankAPINotify 4e4635f404784080a5c548da91f97f1e-CHUYEN TIEN'))
|
|
.toBe('4e4635f4-0478-4080-a5c5-48da91f97f1e');
|
|
});
|
|
|
|
it('returns null for invalid content', () => {
|
|
expect(parseOrderIdFromContent('CLAUDEKIT')).toBeNull();
|
|
expect(parseOrderIdFromContent('4e4635f4-0478')).toBeNull();
|
|
expect(parseOrderIdFromContent('104588021672-CLAUDEKIT')).toBeNull();
|
|
});
|
|
});
|
|
```
|
|
|
|
### Webhook Integration Test Script
|
|
```bash
|
|
#!/bin/bash
|
|
# scripts/test-sepay-webhook.sh
|
|
|
|
BASE_URL="http://localhost:3000/api/webhooks/sepay"
|
|
API_KEY="your-test-key"
|
|
|
|
# Test 1: Valid Bearer token
|
|
echo "Test 1: Bearer token auth"
|
|
curl -X POST "$BASE_URL" \
|
|
-H "Authorization: Bearer $API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"id":12345,"content":"CLAUDEKIT test-uuid","transferAmount":2450000,"transferType":"in"}'
|
|
|
|
# Test 2: Valid Apikey format
|
|
echo "Test 2: Apikey auth"
|
|
curl -X POST "$BASE_URL" \
|
|
-H "Authorization: Apikey $API_KEY" \
|
|
-d '{"id":12346,"content":"CLAUDEKIT test-uuid","transferAmount":2450000,"transferType":"in"}'
|
|
|
|
# Test 3: Missing auth (should return 401)
|
|
echo "Test 3: No auth (expect 401)"
|
|
curl -X POST "$BASE_URL" \
|
|
-d '{"id":12347,"content":"test","transferAmount":100000,"transferType":"in"}'
|
|
|
|
# Test 4: Invalid key (should return 401)
|
|
echo "Test 4: Invalid key (expect 401)"
|
|
curl -X POST "$BASE_URL" \
|
|
-H "Authorization: Bearer wrong-key" \
|
|
-d '{"id":12348,"content":"test","transferAmount":100000,"transferType":"in"}'
|
|
```
|
|
|
|
## Database Schema
|
|
|
|
### Orders Table Extensions for SePay
|
|
```typescript
|
|
// Fields used specifically for SePay
|
|
{
|
|
paymentId: text('payment_id'), // Transaction content or TEAM{8} code
|
|
paymentProvider: literal('sepay'), // Distinguishes from Polar
|
|
currency: literal('VND'), // Always VND for SePay
|
|
amount: integer('amount'), // In VND (no decimals)
|
|
}
|
|
|
|
// Metadata JSON includes:
|
|
{
|
|
gateway: string, // Bank name from webhook
|
|
transactionDate: string, // Webhook timestamp
|
|
transactionId: number, // SePay transaction ID
|
|
transferAmount: number, // Actual received amount
|
|
matchMethod: string, // How order was matched
|
|
content: string, // Original transaction memo
|
|
encryptedTaxId?: string, // For VAT invoices
|
|
}
|
|
```
|
|
|
|
### Recommended Indexes
|
|
```sql
|
|
CREATE INDEX idx_orders_sepay_pending ON orders (status, payment_provider, amount)
|
|
WHERE status = 'pending' AND payment_provider = 'sepay';
|
|
|
|
CREATE INDEX idx_orders_sepay_timestamp ON orders (created_at)
|
|
WHERE payment_provider = 'sepay';
|
|
|
|
CREATE INDEX idx_orders_payment_id ON orders (payment_id)
|
|
WHERE payment_provider = 'sepay';
|
|
```
|
|
|
|
## Production Checklist
|
|
|
|
- [ ] Environment variables configured
|
|
- [ ] Bank account verified and active
|
|
- [ ] Webhook endpoint publicly accessible (HTTPS)
|
|
- [ ] Webhook API key set and verified
|
|
- [ ] Timing-safe auth comparison implemented
|
|
- [ ] Idempotency handling tested with duplicate webhooks
|
|
- [ ] UUID parsing tested with real Vietnamese bank memos
|
|
- [ ] Amount validation (underpayment rejection) tested
|
|
- [ ] Overpayment handling verified
|
|
- [ ] Currency conversion fallback chain tested
|
|
- [ ] Invoice email template tested
|
|
- [ ] Error monitoring enabled
|
|
- [ ] Structured logging in place
|
|
- [ ] Database indexes created
|
|
- [ ] Polar discount sync tested (for shared coupons)
|
|
- [ ] Team payment ID format tested
|
|
- [ ] Non-blocking operations wrapped in try-catch
|
|
- [ ] Always-200 webhook response verified
|
|
|
|
## Common Pitfalls
|
|
|
|
1. **Not handling bank dash-stripping** - Banks may remove dashes from UUIDs
|
|
2. **Rejecting overpayments** - Should accept; customer paid more
|
|
3. **Blocking webhook on non-critical failures** - Wrap in try-catch, continue
|
|
4. **Not using timing-safe comparison** - Vulnerable to timing attacks
|
|
5. **Returning non-200 on error** - Causes SePay retry loops
|
|
6. **Using raw exchange rates without fallback** - API can fail
|
|
7. **Applying discounts in wrong order** - Always coupon first, then referral
|
|
8. **Not logging matchMethod** - Hard to debug failed matches
|
|
9. **Not preserving checkout metadata** - Lose discount audit trail
|
|
10. **Synchronous Polar discount sync** - Can fail; use retry with backoff
|
|
11. **Case-sensitive content matching** - Banks may uppercase/lowercase
|
|
12. **Missing amount-only match safety** - Reject ambiguous matches
|