agentsclimarketplace

Stripe game payments

Skill fcsouza/agent-skills/skills/stripe-game-payments

Use when implementing game payments, in-app purchases, subscriptions, Stripe webhooks, or monetization flows. Triggers: payments, IAP, subscription, Stripe, checkout, webhooks, monetization.From its SKILL.md

Install
npx -y skills add fcsouza/agent-skills --skill stripe-game-payments

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

6.5 KB, as published. Nobody here has run it

Stripe Game Payments

Purpose

In-app purchases, subscriptions, consumables, webhooks, idempotency, and fraud prevention for games using Stripe.

When to Use

Trigger: payments, Stripe, IAP, in-app purchase, subscription, premium, battle pass, virtual currency, webhook, checkout, monetization

Prerequisites

  • postgres-game-schema (player accounts, inventory, currency tables)
  • betterauth-integration (authenticated player sessions)

Core Principles

Sid Meier: "A game is a series of interesting decisions." Monetization should enable interesting decisions, not replace them.

  1. Payments are server-side only — never trust the client with price, quantity, or entitlement logic
  2. Idempotency keys on every mutation — prevent double-charges on retries or network failures
  3. Webhook-first fulfillment — deliver purchases via webhook events, not checkout completion callbacks
  4. Two-phase fulfillment — record the purchase first, then queue reward delivery separately
  5. Support both one-time and recurring — consumables (currency packs, items) and subscriptions (battle pass, premium membership)
  6. Currency abstraction — players buy premium currency, then spend it on items; never sell game items directly for real money
  7. Refund handling — revoke rewards on chargebacks and refunds automatically
  8. Fraud signals — velocity checks, suspicious purchase patterns, geographic anomalies

Step-by-Step Instructions

1. Install Dependencies

bun add stripe

2. Configure Stripe Client

Use boilerplate/stripe-setup.ts to initialize the Stripe SDK, sync your product catalog, and link Stripe customers to player accounts.

3. Define Product Catalog

Start with templates/product-catalog.ts to define your product types (consumable, subscription, currency bundle, cosmetic) and map them to Stripe price IDs and game rewards.

4. Create Checkout Sessions

Use boilerplate/checkout.ts to create Stripe Checkout sessions for one-time purchases, subscriptions, and premium currency bundles. Always attach player metadata.

5. Handle Webhooks

Implement boilerplate/webhooks.ts for signature verification, idempotent event processing, and two-phase fulfillment. Route events to typed handlers defined in templates/webhook-events.ts.

6. Queue Reward Delivery

After recording a purchase, dispatch a fulfillment job via BullMQ (see bullmq-game-queues). The worker grants the items, currency, or subscription entitlement.

7. Handle Refunds & Chargebacks

Listen for charge.refunded and charge.dispute.* events. Revoke granted rewards, deduct premium currency, and flag the player account for review.

8. Monitor & Audit

Log every payment event with an audit trail. Track fulfillment status (pending, fulfilled, revoked) and alert on anomalies.

Code Examples

Creating a checkout for a currency bundle

import { createCurrencyBundleCheckout } from './checkout';

const session = await createCurrencyBundleCheckout({
  playerId: 'player_123',
  priceId: 'price_premium_1000',
  quantity: 1,
  successUrl: 'https://game.example.com/store/success',
  cancelUrl: 'https://game.example.com/store',
});

Creating a subscription checkout

import { createSubscriptionCheckout } from './checkout';

const session = await createSubscriptionCheckout({
  playerId: 'player_123',
  priceId: 'price_battle_pass_monthly',
  successUrl: 'https://game.example.com/pass/success',
  cancelUrl: 'https://game.example.com/pass',
});

Processing a webhook event

import { handleStripeWebhook } from './webhooks';

app.post('/webhooks/stripe', async ({ request }) => {
  const sig = request.headers.get('stripe-signature')!;
  const body = await request.text();
  await handleStripeWebhook(body, sig);
  return new Response('ok', { status: 200 });
});

See boilerplate/stripe-setup.ts for client configuration, boilerplate/checkout.ts for session creation, boilerplate/webhooks.ts for event handling, and templates/product-catalog.ts for product definitions.

Cross-References

  • betterauth-integration for authenticated player sessions and Stripe customer linking
  • postgres-game-schema for purchase records, inventory, and currency tables
  • bullmq-game-queues for async fulfillment job dispatch and processing
  • game-economy-design for pricing strategy and currency balance design

Pitfalls & Anti-Patterns

  • Don't fulfill purchases on checkout completion — always use webhooks; checkout success redirects can be faked or missed
  • Don't skip idempotency keys — network retries and webhook replays will cause double-charges or double-grants without them
  • Don't store Stripe API keys in client code — all payment logic must be server-side only
  • Don't sell game items directly for real money — use a premium currency layer so you can adjust prices without changing Stripe products
  • Don't ignore chargebacks — unhandled disputes lead to account bans by Stripe; always revoke rewards and flag accounts
  • Don't couple payment processing with reward delivery — use two-phase fulfillment so a failed reward grant doesn't block payment recording
  • Don't skip webhook signature verification — unsigned webhooks can be spoofed to grant free items
  • Don't allow unlimited purchase velocity — rate-limit purchases per player to detect fraud and prevent accidental overspending

Designer Philosophy

Sid Meier: Monetization should enable interesting decisions, not replace them. A well-designed payment system gives players meaningful choices about how they engage with content. Premium currency buys time, not power. A battle pass rewards engagement, not spending. Fair monetization respects player skill and time investment — the best purchases enhance the experience without gating core gameplay.

Sources

Keep looking

Skills are one crate of 613,531. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.