← Back to Community Credits

Technical Appendix: Promo Code Integration

For Whop Reviewers & Security AuditorsLast Updated: January 30, 2026
This document provides a technical overview of Community Credits' promo code integration with Whop Plans. It is intended for platform reviewers and security auditors to understand the safeguards in place.

Security Summary

15-minute hold TTLHMAC-SHA256 webhooksAtomic state transitionsIdempotency keysIdentity verificationPlan verificationAudit loggingImmediate fraud refund

1. Architecture Overview

The integration uses a hold/settle pattern where credits are held (not spent) when a checkout is initiated, and only settled after Whop confirms completion via webhook.
1. User initiates purchase → Credits HELD
2. 100% promo code created → User redirected to Whop
3. User completes checkout → Webhook received
4. Identity + Plan verified → Credits SETTLED
   OR
   Verification fails → Credits REFUNDED immediately
   OR
   TTL expires (15 min) → Credits REFUNDED automatically

2. Checkout State Machine

All state transitions are atomic and use database-level constraints to prevent race conditions.
StateDescriptionCreditscreatedPromo code generated, user not yet redirectedHeldredirectedUser sent to Whop checkoutHeldcompletedWebhook confirmed, purchase successfulSettledexpiredTTL passed without completionRefundedreversedManually reversed/refundedRefundedfraud_blockedUser/plan mismatch detectedRefunded immediately

3. Fraud Prevention Measures

User Identity Verification

  • The user_id from the webhook is compared against the original purchaser
  • If mismatch detected: checkout is marked fraud_blocked
  • Credits are immediately refunded to the original user
  • Event is logged to audit trail with both user IDs

Plan ID Verification

  • The plan_id from the webhook is compared against the expected plan
  • Prevents promo codes from being used on different (potentially more expensive) plans
  • If mismatch detected: checkout is marked fraud_blocked
  • Credits are immediately refunded to the original user

Rate Limiting

  • Maximum 10 checkout attempts per user per hour
  • Maximum 3 attempts per specific option per hour
  • Active checkout detection prevents duplicate holds

4. Webhook Security

  • Signature Verification: HMAC-SHA256 with shared secret
  • Header: x-whop-signature
  • Events Processed: checkout.completed, membership.created
  • Promo Code Filter: Only CREDITS-* prefixed codes are processed

5. Idempotency

Idempotency keys include all relevant fields to prevent both duplicate processing and false-positive blocking of different purchases:
{userId}:{gatewayId}:{optionId}:{whopPlanId}:{creditsAmount}:{5minBucket}
  • 5-minute time buckets allow retries within the same window
  • Different options generate different keys (no blocking)
  • Same option + same time = returns existing checkout URL

6. Atomic State Transitions

All state transitions use updateMany with WHERE conditions to ensure atomicity:
// Only complete if in pending state AND not expired
UPDATE pending_promo_checkouts
SET status = 'completed'
WHERE promo_code = ?
  AND status IN ('created', 'redirected')
  AND expires_at > NOW()

// If count = 0, race condition occurred
This prevents:
  • Double-settle (webhook arrives twice)
  • Settle after expire (webhook arrives after cron processed it)
  • Double-refund (cron and manual reversal race)

7. Audit Logging

All checkout events are logged to promo_checkout_audit_log for compliance and dispute resolution:
Event TypeDescriptionhold_createdCredits held, promo code generatedcheckout_redirectedUser redirected to Whop checkoutwebhook_receivedWebhook received from Whopcheckout_completedCheckout successfully settledcheckout_expiredTTL expired, credits refundedcredits_refundedCredits returned to useruser_mismatchFraud: different user completed checkoutplan_mismatchFraud: different plan was purchasedrace_conditionConcurrent state transition detected

8. Merchant Consent

Before a gateway can use Whop Plan integration:
  • Merchant must explicitly acknowledge promo code flow
  • Consent includes understanding of user verification
  • Merchant is responsible for selecting appropriate plans
  • Consent timestamp is recorded for audit purposes

Summary

The promo code integration is designed with multiple layers of protection:
  • Credits are never spent until Whop confirms completion
  • Identity and plan verification prevents fraud
  • Atomic transitions prevent race conditions
  • Comprehensive audit logging enables investigations
  • Immediate refunds on fraud protect users