algoderiv/stripe

Stripe Development & Integration

Stripe is a payment infrastructure platform providing APIs and tools for internet commerce. This skill covers the core development workflows: API authentication, payment processing, webhook handling, error management, testing strategies, and building multi-party platforms with Stripe Connect.

When to Use This Skill

This skill should be triggered when:

• Integrating Stripe payments (checkout, subscriptions, invoices)
• Setting up API keys and authentication
• Implementing webhook endpoints and signature verification
• Handling Stripe errors and decline codes
• Testing with sandbox/test cards
• Building platforms or marketplaces with Stripe Connect
• Managing connected accounts, charges, transfers, and payouts
• Using Stripe SDKs (Node.js, Python, Ruby, Go, Java, PHP, .NET)
• Debugging Stripe API issues

Quick Reference

API Base URL

https://api.stripe.com

Authentication

# Secret key (server-side only)
curl https://api.stripe.com/v1/charges \
  -u sk_test_xxxx:

# Or via Authorization header
curl https://api.stripe.com/v1/charges \
  -H "Authorization: Bearer sk_test_xxxx"

Key Prefixes

| Mode | Secret Key | Publishable Key | Restricted Key | |------|-----------|-----------------|----------------| | Sandbox | sk_test_ | pk_test_ | rk_test_ | | Live | sk_live_ | pk_live_ | rk_live_ |

Available SDKs

| Platform | Package | |----------|---------| | Node.js | stripe | | Python | stripe | | Ruby | stripe | | Go | github.com/stripe/stripe-go | | Java | com.stripe:stripe-java | | PHP | stripe/stripe-php | | .NET | Stripe.net | | React (web) | @stripe/react-stripe-js | | iOS | StripePaymentSheet | | Android | com.stripe:stripe-android | | React Native | @stripe/stripe-react-native |

Common Test Cards

| Card | Number | PaymentMethod | |------|--------|---------------| | Visa | 4242424242424242 | pm_card_visa | | Visa (debit) | 4000056655665556 | pm_card_visa_debit | | Mastercard | 5555555555554444 | pm_card_mastercard | | Amex | 378282246310005 | pm_card_amex | | Declined | 4000000000000002 | pm_card_chargeDeclined | | Fraud block | - | pm_card_radarBlock | | Expired | - | pm_card_chargeDeclinedExpiredCard |

Use any future expiry date, any 3-digit CVC (4 for Amex), any other values.

Create a Payment Intent (curl)

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_xxx: \
  -d amount=2000 \
  -d currency=usd \
  -d "payment_method_types[]"=card

Connect Charge Types

| Type | Use Case | Fund Flow | |------|----------|-----------| | Direct charges | SaaS platforms | Customer → Connected Account → Platform fee | | Destination charges | Marketplaces | Customer → Platform → Connected Account | | Separate charges & transfers | Complex splits | Customer → Platform → Multiple accounts |

Webhook Signature Verification (Node.js)

const stripe = require('stripe')('sk_test_xxx');
const endpointSecret = 'whsec_xxx';

app.post('/webhook', (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  // Handle event
  res.status(200).json({received: true});
});

Error Types

| Exception Class | HTTP | Cause | |----------------|------|-------| | CardError | 402 | Payment declined / card issue | | InvalidRequestError | 400 | Wrong parameters or invalid state | | AuthenticationError | 401 | Bad API key | | RateLimitError | 429 | Too many requests | | APIConnectionError | - | Network failure | | APIError | 500 | Stripe server error | | IdempotencyError | 400 | Mismatched idempotency key | | PermissionError | 403 | Restricted key lacks permissions | | SignatureVerificationError | - | Invalid webhook signature |

References

• api-keys-auth.md - API keys, authentication, security best practices, key management
• error-handling.md - Error types, exception handling patterns, test cards for errors
• webhooks.md - Webhook setup, signature verification, event handling, testing, best practices
• testing.md - Sandbox environment, test card numbers by brand/country, PaymentMethods, going live
• connect-overview.md - Connect platform design, account types, charge types, onboarding, payouts
• connect-charges.md - Direct/destination/separate charges, platform fees, fund flow
• development-essentials.md - SDKs, expanding objects, pagination, idempotency, versioning, metadata