Payments & Retail — Colorful Moves

Providers Multi-provider

💳 Stripe

Primary payment provider. Subscription billing via Checkout Sessions, Customer Portal for self-service, and webhook lifecycle management.

Primary Wired

🔲 Square

Backup checkout provider. Creates payment links via Square Orders API. Auto-fallback on landing when Stripe is unavailable.

Backup Wired

🪙 Coin Wallet

On-chain payments via NOMA/OPC tokens. Verify transactions, stake for tier unlock, and check balances on Sepolia.

Sepolia ERC-20

Stripe Checkout Flow

1

User clicks "Upgrade to Pro" on landing page. Frontend calls POST /api/checkout with their API key.

2

Worker creates Stripe Checkout Session with price ID, metadata (api_key_id, tier), and redirect URLs.

3

User pays on Stripe. Card, Apple Pay, Google Pay — whatever Stripe supports in their region.

4

Stripe webhook fires checkout.session.completed → Worker verifies HMAC → upgrades tier in D1.

5

User redirected back to ?checkout=success with "Manage Billing" button active.

# Create checkout session
curl -X POST "https://api.colorfulmoves.com/api/checkout" \
  -H "X-API-Key: cm_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tier":"pro","success_url":"https://...","cancel_url":"https://..."}'

# Response
{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_test_...",
  "tier": "pro"
}
      

Subscription Lifecycle Events

✅ checkout.session.completed

Payment successful. Upgrade user to Pro/Enterprise. Increase daily/monthly limits. Send welcome email.

⚠️ invoice.payment_failed

Card declined. Mark subscription past_due. Email user with update link. Grace period: 3 days.

✅ invoice.payment_succeeded

Card retry successful. Reactivate subscription. Remove past_due status.

🔄 customer.subscription.updated

Plan changed (upgrade/downgrade). Sync new tier and limits in D1 automatically.

❌ customer.subscription.deleted

Subscription canceled. Downgrade to Free tier. Reset limits. Send cancellation notice.

🔐 HMAC Verification

Every webhook verified with Stripe-Signature header. Invalid signatures rejected with 401.

Usage Top-Ups Emergency

Hit your daily limit? Buy extra requests without upgrading your subscription tier. Instant activation via Stripe one-time payment.

Pack	Requests	Price	Best For
Small	+100	$4.99	Quick burst, testing
Medium	+500	$19.99	Day of heavy usage
Large	+1,000	$34.99	Best value — extended work

curl -X POST "https://api.colorfulmoves.com/api/topup" \
  -H "X-API-Key: cm_xxx" \
  -d '{"amount":100}'
      

Customer Portal

Self-service billing management powered by Stripe Customer Portal.

💳 Update Card

Add new payment method, set default, remove expired cards.

📅 View Invoices

Download PDF invoices, view payment history, check upcoming charges.

⬇️ Downgrade

Switch from Pro to Free at end of billing period. No immediate cutoff.

❌ Cancel

Immediate cancellation with prorated refund (configurable in Stripe).

Webhook Configuration

# Endpoint URL
https://api.colorfulmoves.com/api/webhooks/stripe

# Required events
checkout.session.completed
invoice.payment_failed
invoice.payment_succeeded
customer.subscription.updated
customer.subscription.deleted

# Secret (set via wrangler)
wrangler secret put STRIPE_WEBHOOK_SECRET  # whsec_xxx from Stripe dashboard
      

Square Backup

If Stripe is not configured or unavailable, the landing page auto-detects and shows a "Pay with Square" button. Creates a Square payment link via the Orders API.

curl -X POST "https://api.colorfulmoves.com/api/checkout/square" \
  -H "X-API-Key: cm_xxx" \
  -d '{"tier":"pro"}'

# Required secrets
wrangler secret put SQUARE_ACCESS_TOKEN     # sandbox-xxx or sq0idp-xxx
wrangler secret put SQUARE_LOCATION_ID      # Lxxx from Square dashboard
wrangler secret put SQUARE_CATALOG_PRO      # catalog object ID for Pro tier
      