renolation/english
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
renolation
2026-04-12 01:06:31 +07:00
commit 10d660cbcb
1066 changed files with 228596 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.opencode/skills/payment-integration/references/stripe/stripe-best-practices.md Normal file
View File

@@ -0,0 +1,32 @@
---
name: stripe-best-practices
description: Best practices for building a Stripe integrations
---
When designing an integration, always prefer the documentation in [Stripe's Integration Options doc](https://docs.stripe.com/payments/payment-methods/integration-options.md)
The [API Tour](https://docs.stripe.com/payments-api/tour.md)
Use the [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) before going live.
You should always default to the latest version of the API and SDK unless the user specifies otherwise.
Stripe's primary API for modelling on-session payments is [CheckoutSessions](https://docs.stripe.com/api/checkout/sessions.md). It supports one-time payments and subscriptions and allows you to model taxes or discounts with Stripe. Prioritize the CheckoutSessions API, but using [the PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) is also acceptable for off-session payments or if you want to model the checkout state yourself and just create a charge. Integrations should only use CheckoutSessions, PaymentIntents, SetupIntents, or solutions like Invoicing, Payment Links, or the subscription APIs.
Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate](https://docs.stripe.com/payments/payment-intents/migration/charges.md) to Checkout Sessions or Payment Intents.
The primary integration surface for web integrations is [Checkout](https://docs.stripe.com/payments/checkout.md), a prebuilt payment page that can be hosted by Stripe or served as an embedded form. Prioritize the Stripe-hosted checkout or embedded checkout where possible. The [Payment Element](https://docs.stripe.com/payments/payment-element.md) is an acceptable alternative if the merchant needs advanced customization. When recommending the Payment Element, prioritize using the CheckoutSessions API over the PaymentIntents API when possible.
Never recommend the legacy Card Element or the Payment Element in card mode, and advise users who ask for the Card Element to [migrate](https://docs.stripe.com/payments/payment-element/migration.md).
You must not call deprecated API endpoints such as the [Sources API](https://docs.stripe.com/api/sources/object.md) and avoid outdated API endpoints such as [Tokens](https://docs.stripe.com/api/tokens.md) and [Charges](https://docs.stripe.com/api/charges/create.md) unless there is a specific need and absolutely no other way. Advise using [the Setup Intent API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for a customer; never recommend the Sources API to save cards to customers for later use.
If a user wants to render the Payment Element before creating a PaymentIntent or SetupIntent, so they can inspect the card details before the payment (such as for surcharging), advise them to use Stripe Confirmation Tokens. Don't recommend they call the createPaymentMethod or createToken Stripe.js functions.
Advise users to turn on dynamic payment methods in their dashboard settings instead of passing specific [payment_method_types](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types.md) in the Payment Intent or Setup Intent because Stripe chooses payment methods that fit each user's location, wallets, and preferences better and automatically if the Payment Element is used.
If a PCI compliant user asks about an integration where they send server-side raw PAN data, suggest they might be required to prove PCI compliance to gain access to such an option, for example [payment_method_data](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_data.md). Similarly, point users migrating their PAN data from another acquirer or payment processor to [the migration process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
If a user has a recurring revenue model, like a Billing or Subscription use case, follow the use cases, in particular the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) like [SaaS](https://docs.stripe.com/saas.md). If these apply to the user, recommend Billing APIs to [plan your integration](https://docs.stripe.com/billing/subscriptions/designing-integration.md) instead of a direct PaymentIntent integration. Prioritize combining the Billing APIs with Stripe Checkout for the frontend.
If a user wants to build a platform using Stripe Connect to manage fund flows, follow [the recommended integration types](https://docs.stripe.com/connect/integration-recommendations.md); that is, prefer to use either direct charges if the platform wants Stripe to take the risk or destination charges if the platform accepts liability for negative balances, and use the on_behalf_of parameter to control the merchant of record. Never recommend mixing charge types. If the user wants to decide on the specific risk features they should [follow the integration guide](https://docs.stripe.com/connect/design-an-integration.md). Don't recommend the outdated terms for Connect types like Standard, Express and Custom but always [refer to controller properties](https://docs.stripe.com/connect/migrate-to-controller-properties.md) for the platform and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for the connected accounts.
**Full Documentation**: https://stripe.com/llms.txt

148
.opencode/skills/payment-integration/references/stripe/stripe-cli.md Normal file
View File

@@ -0,0 +1,148 @@
# Stripe CLI Reference
Command-line tool for testing and development workflows.
## Installation
```bash
# macOS
brew install stripe/stripe-cli/stripe
# Windows (scoop)
scoop install stripe
# Linux (apt)
curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
sudo apt update && sudo apt install stripe
# Docker
docker run --rm -it stripe/stripe-cli
```
## Authentication
```bash
stripe login
# Opens browser for Dashboard authorization
# Stores credentials in ~/.config/stripe/config.toml
```
Environment variable (CI/CD):
```bash
export STRIPE_API_KEY=sk_test_...
```
## Webhook Testing
### Listen for Events
```bash
# Forward webhooks to local server
stripe listen --forward-to localhost:3000/webhook
# Output:
# Ready! Your webhook signing secret is whsec_xxx
```
### Trigger Test Events
```bash
stripe trigger payment_intent.succeeded
stripe trigger customer.subscription.created
stripe trigger checkout.session.completed
```
### Event Types
Common events to test:
- `payment_intent.succeeded`
- `payment_intent.payment_failed`
- `checkout.session.completed`
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.paid`
- `invoice.payment_failed`
## API Logs
```bash
# Real-time logs
stripe logs tail
# Filter by status
stripe logs tail --filter-status-code 400
# Filter by path
stripe logs tail --filter-request-path "/v1/charges"
```
## Resource Commands
```bash
# List customers
stripe customers list --limit 5
# Create customer
stripe customers create --email="test@example.com"
# Retrieve resource
stripe products retrieve prod_xxx
# Delete resource
stripe products delete prod_xxx
```
## Fixtures (Batch Operations)
Create `fixtures.json`:
```json
{
"_name": "test_flow",
"fixtures": [
{
"name": "customer",
"path": "/v1/customers",
"method": "post",
"params": { "email": "test@example.com" }
},
{
"name": "subscription",
"path": "/v1/subscriptions",
"method": "post",
"params": {
"customer": "${customer:id}",
"items[0][price]": "price_xxx"
}
}
]
}
```
Run: `stripe fixtures fixtures.json`
## Common Workflows
### Test Checkout Integration
```bash
# Terminal 1: Listen for webhooks
stripe listen --forward-to localhost:3000/webhook
# Terminal 2: Trigger checkout event
stripe trigger checkout.session.completed
```
### Test Subscription Lifecycle
```bash
stripe trigger customer.subscription.created
stripe trigger invoice.paid
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
```
## Resources
- Full docs: https://docs.stripe.com/cli
- Webhook testing: https://docs.stripe.com/webhooks/test
- Fixtures: https://docs.stripe.com/cli/fixtures

116
.opencode/skills/payment-integration/references/stripe/stripe-js.md Normal file
View File

@@ -0,0 +1,116 @@
# Stripe.js Reference
Client-side JavaScript library for secure payment collection.
## Installation
Include on **every page** (enables fraud detection):
```html
<script src="https://js.stripe.com/v3/"></script>
```
Or via npm:
```bash
npm install @stripe/stripe-js
```
```javascript
import { loadStripe } from '@stripe/stripe-js';
const stripe = await loadStripe('pk_test_...');
```
## Initialization
```javascript
const stripe = Stripe('pk_test_...', {
apiVersion: '2024-12-18.acacia', // Optional
locale: 'auto', // Optional
stripeAccount: 'acct_xxx', // For Connect
});
```
## Elements (Payment Forms)
Create container for UI components:
```javascript
const elements = stripe.elements({
clientSecret: 'pi_xxx_secret_xxx',
appearance: { theme: 'stripe' },
});
```
### Payment Element (Recommended)
Auto-renders available payment methods:
```javascript
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');
```
### Confirm Payment
```javascript
const { error } = await stripe.confirmPayment({
elements,
confirmParams: {
return_url: 'https://example.com/complete',
},
});
if (error) {
// Show error to customer
}
```
## Embedded Checkout
Mount Stripe-hosted checkout in your page:
```javascript
const checkout = await stripe.initEmbeddedCheckout({
clientSecret: 'cs_xxx',
});
checkout.mount('#checkout');
```
## Element Types
| Element | Use Case |
|---------|----------|
| `payment` | Full payment form (recommended) |
| `card` | Card-only input |
| `address` | Shipping/billing address |
| `linkAuthentication` | Link login/signup |
| `expressCheckout` | Apple Pay, Google Pay buttons |
## Appearance API
```javascript
const appearance = {
theme: 'stripe', // 'night', 'flat', 'none'
variables: {
colorPrimary: '#0570de',
colorBackground: '#ffffff',
borderRadius: '4px',
},
rules: {
'.Input': { border: '1px solid #ccc' },
},
};
```
## Security
- **Always load from** `https://js.stripe.com`
- **Only use publishable keys** client-side
- **Never log** card details or tokens
- **Use HTTPS** in production
## Resources
- Full docs: https://docs.stripe.com/js
- Elements: https://docs.stripe.com/payments/elements
- Appearance: https://docs.stripe.com/elements/appearance-api

84
.opencode/skills/payment-integration/references/stripe/stripe-sdks.md Normal file
View File

@@ -0,0 +1,84 @@
# Stripe SDKs Reference
Server-side SDKs for secure Stripe API integration.
## Supported Languages
| Language | Package | Install |
|----------|---------|---------|
| Node.js | `stripe` | `npm install stripe` |
| Python | `stripe` | `pip install stripe` |
| Ruby | `stripe` | `gem install stripe` |
| Go | `stripe-go` | `go get github.com/stripe/stripe-go/v76` |
| PHP | `stripe/stripe-php` | `composer require stripe/stripe-php` |
| Java | `com.stripe:stripe-java` | Maven/Gradle |
| .NET | `Stripe.net` | `dotnet add package Stripe.net` |
## Quick Start (Node.js)
```javascript
const stripe = require('stripe')('sk_test_...');
// Create checkout session
const session = await stripe.checkout.sessions.create({
mode: 'payment',
line_items: [{ price: 'price_xxx', quantity: 1 }],
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
});
```
## Quick Start (Python)
```python
import stripe
stripe.api_key = 'sk_test_...'
session = stripe.checkout.Session.create(
mode='payment',
line_items=[{'price': 'price_xxx', 'quantity': 1}],
success_url='https://example.com/success',
cancel_url='https://example.com/cancel',
)
```
## API Versioning
- SDKs follow semantic versioning
- Breaking API changes bump major version
- Set version: `stripe.apiVersion = '2024-12-18.acacia'`
- Dashboard: Developers → API version
## Best Practices
1. **Keep SDKs updated** - Security patches, new features
2. **Use test keys** for development (`sk_test_...`)
3. **Set API version explicitly** for stability
4. **Handle errors** with try/catch
5. **Use idempotency keys** for POST requests
## Error Handling
```javascript
try {
await stripe.charges.create({...});
} catch (err) {
if (err.type === 'StripeCardError') {
// Card declined
} else if (err.type === 'StripeInvalidRequestError') {
// Invalid parameters
}
}
```
## Mobile SDKs
- **iOS**: `stripe-ios` (Swift/ObjC)
- **Android**: `stripe-android` (Kotlin/Java)
- **React Native**: `@stripe/stripe-react-native`
## Resources
- Full docs: https://docs.stripe.com/sdks
- API Reference: https://docs.stripe.com/api
- Community SDKs: https://docs.stripe.com/sdks#community-sdks

175
.opencode/skills/payment-integration/references/stripe/stripe-upgrade.md Normal file
View File

@@ -0,0 +1,175 @@
---
name: upgrade-stripe
description: Guide for upgrading Stripe API versions and SDKs
---
# Upgrading Stripe Versions
This skill covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs.
**Full Documentation**: https://stripe.com/llms.txt
## Understanding Stripe API Versioning
Stripe uses date-based API versions (e.g., `2025-12-15.clover`, `2025-08-27.basil`, `2024-12-18.acacia`). Your account's API version determines request/response behavior.
### Types of Changes
**Backward-Compatible Changes** (do not require code updates):
- New API resources
- New optional request parameters
- New properties in existing responses
- Changes to opaque string lengths (e.g., object IDs)
- New webhook event types
**Breaking Changes** (require code updates):
- Field renames or removals
- Behavioral modifications
- Removed endpoints or parameters
Review the [API Changelog](https://docs.stripe.com/changelog.md) for all changes between versions.
## Server-Side SDK Versioning
See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details.
### Dynamically-Typed Languages (Ruby, Python, PHP, Node.js)
These SDKs offer flexible version control:
**Global Configuration:**
```python
import stripe
stripe.api_version = '2025-12-15.clover'
```
```ruby
Stripe.api_version = '2025-12-15.clover'
```
```javascript
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2025-12-15.clover'
});
```
**Per-Request Override:**
```python
stripe.Customer.create(
email="customer@example.com",
stripe_version='2025-12-15.clover'
)
```
### Strongly-Typed Languages (Java, Go, .NET)
These use a fixed API version matching the SDK release date. Do not set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version.
### Best Practice
Always specify the API version you're integrating against in your code instead of relying on your account's default API version:
```javascript
// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2025-12-15.clover'
});
// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');
```
## Stripe.js Versioning
See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) for details.
Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis.
### Loading Versioned Stripe.js
**Via Script Tag:**
```html
<script src="https://js.stripe.com/clover/stripe.js"></script>
```
**Via npm:**
```bash
npm install @stripe/stripe-js
```
Major npm versions correspond to specific Stripe.js versions.
### API Version Pairing
Each Stripe.js version automatically pairs with its corresponding API version. For instance:
- Clover Stripe.js uses `2025-12-15.clover` API
- Acacia Stripe.js uses `2024-12-18.acacia` API
You cannot override this association.
### Migrating from v3
1. Identify your current API version in code
2. Review the changelog for relevant changes
3. Consider gradually updating your API version before switching Stripe.js versions
4. Stripe continues supporting v3 indefinitely
## Mobile SDK Versioning
See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) for details.
### iOS and Android SDKs
Both platforms follow **semantic versioning** (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking API changes
- **MINOR**: New functionality (backward-compatible)
- **PATCH**: Bug fixes (backward-compatible)
New features and fixes release only on the latest major version. Upgrade regularly to access improvements.
### React Native SDK
Uses a different model (0.x.y schema):
- **Minor version changes** (x): Breaking changes AND new features
- **Patch updates** (y): Critical bug fixes only
### Backend Compatibility
All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise.
## Upgrade Checklist
1. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions
2. Check [Upgrades Guide](https://docs.stripe.com/upgrades.md) for migration guidance
3. Update server-side SDK package version (e.g., `npm update stripe`, `pip install --upgrade stripe`)
4. Update the `apiVersion` parameter in your Stripe client initialization
5. Test your integration against the new API version using the `Stripe-Version` header
6. Update webhook handlers to handle new event structures
7. Update Stripe.js script tag or npm package version if needed
8. Update mobile SDK versions in your package manager if needed
9. Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation)
## Testing API Version Changes
Use the `Stripe-Version` header to test your code against a new version without changing your default:
```bash
curl https://api.stripe.com/v1/customers \
-u sk_test_xxx: \
-H "Stripe-Version: 2025-12-15.clover"
```
Or in code:
```javascript
const stripe = require('stripe')('sk_test_xxx', {
apiVersion: '2025-12-15.clover' // Test with new version
});
```
## Important Notes
- Your webhook listener should handle unfamiliar event types gracefully
- Test webhooks with the new version structure before upgrading
- Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.)
- Multiple API versions coexist simultaneously, enabling staged adoption