@stella-studio/ck 1.0.0

package/.claude/skills/payment-integration/references/sepay/webhooks.md

@@ -0,0 +1,208 @@
+# SePay Webhooks
+
+Real-time payment notifications from SePay to your server.
+
+## Setup
+
+1. Access WebHooks menu in dashboard
+2. Click "+ Add webhooks"
+3. Configure:
+   - **Name:** Descriptive identifier
+   - **Event Selection:** `All`, `In_only`, `Out_only`
+   - **Conditions:** Bank accounts, VA filtering, payment code requirements
+   - **Webhook URL:** Your callback endpoint (must be publicly accessible)
+   - **Is Verify Payment:** Flag for validation
+   - **Authentication:** `No_Authen`, `OAuth2.0`, or `Api_Key`
+4. Click "Add" to finalize
+
+## Payload Structure
+
+```json
+{
+  "id": 92704,
+  "gateway": "Vietcombank",
+  "transactionDate": "2023-03-25 14:02:37",
+  "accountNumber": "0123499999",
+  "code": null,
+  "content": "payment content",
+  "transferType": "in",
+  "transferAmount": 2277000,
+  "accumulated": 19077000,
+  "subAccount": null,
+  "referenceCode": "MBVCB.3278907687"
+}
+```
+
+**Fields:**
+- `id` - Unique transaction ID (use for deduplication)
+- `gateway` - Bank name
+- `transactionDate` - Transaction timestamp
+- `accountNumber` - Bank account number
+- `code` - Payment code (if available)
+- `content` - Transfer description/content
+- `transferType` - "in" (incoming) or "out" (outgoing)
+- `transferAmount` - Transaction amount
+- `accumulated` - Account balance after transaction
+- `subAccount` - Sub-account identifier
+- `referenceCode` - Bank transaction reference
+
+## Authentication
+
+**API Key:**
+```
+Authorization: Apikey YOUR_KEY
+Content-Type: application/json
+```
+
+**OAuth 2.0:**
+Provide token endpoint, client ID, and client secret in dashboard.
+
+**No Authentication:**
+Available but not recommended for production. Consider IP whitelisting.
+
+## Response Requirements
+
+**Success Response:**
+```json
+HTTP/1.1 200 OK
+{
+  "success": true
+}
+```
+
+**Accepted:** Any 2xx status code (200-201)
+**Timeout:** Respond within 5 seconds
+
+## Auto-Retry Mechanism
+
+**Policy:**
+- Retries up to 7 times over ~5 hours
+- Fibonacci sequence intervals (1, 1, 2, 3, 5, 8, 13... minutes)
+
+**Duplicate Prevention:**
+```javascript
+// Primary: Use transaction ID
+const exists = await db.transactions.findOne({ sepay_id: data.id });
+if (exists) return { success: true };
+
+// Alternative: Composite key
+const key = `${data.referenceCode}-${data.transferType}-${data.transferAmount}`;
+```
+
+## Implementation Examples
+
+### Node.js/Express
+```javascript
+app.post('/webhook/sepay', async (req, res) => {
+  const transaction = req.body;
+
+  // Check duplicates
+  if (await isDuplicate(transaction.id)) {
+    return res.json({ success: true });
+  }
+
+  // Process transaction
+  if (transaction.transferType === 'in') {
+    await processPayment({
+      amount: transaction.transferAmount,
+      content: transaction.content,
+      referenceCode: transaction.referenceCode
+    });
+  }
+
+  // Save to database
+  await db.transactions.insert(transaction);
+
+  res.json({ success: true });
+});
+```
+
+### PHP
+```php
+<?php
+$data = json_decode(file_get_contents('php://input'), true);
+
+// Check duplicates
+$exists = $db->query("SELECT id FROM transactions WHERE sepay_id = ?", [$data['id']]);
+if ($exists) {
+    echo json_encode(['success' => true]);
+    exit;
+}
+
+// Process payment
+if ($data['transferType'] == 'in') {
+    processPayment($data['transferAmount'], $data['content']);
+}
+
+// Save to database
+$db->insert('transactions', [
+    'sepay_id' => $data['id'],
+    'amount' => $data['transferAmount'],
+    'content' => $data['content'],
+    'reference_code' => $data['referenceCode']
+]);
+
+header('Content-Type: application/json');
+echo json_encode(['success' => true]);
+```
+
+## Security Best Practices
+
+1. **IP Whitelisting:** Restrict endpoint to SePay IPs
+2. **API Key Verification:** Validate authorization header
+3. **HTTPS Only:** Use SSL/TLS
+4. **Duplicate Detection:** Prevent double processing
+5. **Logging:** Maintain webhook logs
+6. **Timeout Handling:** Respond quickly (<5s)
+7. **Idempotency:** Same webhook multiple times = same result
+
+## Monitoring
+
+**Dashboard Features:**
+- View webhook attempts
+- Check response status
+- Review retry history
+- Manual retry option
+
+**Application Monitoring:**
+- Log all webhook receipts
+- Track processing time
+- Alert on failures
+- Monitor duplicate rate
+
+## OAuth2 Webhook Management API
+
+**Available Scopes:** `webhook:read`, `webhook:write`, `webhook:delete`
+
+**List Webhooks:**
+```
+GET /api/v1/webhooks
+```
+
+**Get Details:**
+```
+GET /api/v1/webhooks/{id}
+```
+
+**Create:**
+```
+POST /api/v1/webhooks
+{
+  "bank_account_id": 123,
+  "name": "My Webhook",
+  "event_type": "All",
+  "authen_type": "Api_Key",
+  "webhook_url": "https://example.com/webhook",
+  "is_verify_payment": true
+}
+```
+
+**Update:**
+```
+PATCH /api/v1/webhooks/{id}
+```
+
+**Delete:**
+```
+DELETE /api/v1/webhooks/{id}
+```

package/.claude/skills/payment-integration/references/stripe/stripe-best-practices.md

@@ -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

package/.claude/skills/payment-integration/references/stripe/stripe-cli.md

@@ -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

package/.claude/skills/payment-integration/references/stripe/stripe-js.md

@@ -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

package/.claude/skills/payment-integration/references/stripe/stripe-sdks.md

@@ -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