@kelviq/mcp-server 0.3.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -30
- package/dist/config.d.ts +5 -0
- package/dist/config.js +31 -10
- package/dist/config.js.map +1 -1
- package/dist/docs/backend-integration/better-auth.md +369 -0
- package/dist/docs/backend-integration/node-sdk.md +373 -5
- package/dist/docs/backend-integration/python-sdk.md +444 -6
- package/dist/docs/changelog/api.md +516 -5
- package/dist/docs/changelog/app.md +162 -0
- package/dist/docs/changelog/cli.md +33 -0
- package/dist/docs/changelog/mcp-server.md +84 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/checkout/apply-a-discount-code.md +150 -0
- package/dist/docs/checkout/checkout-configuration.md +88 -22
- package/dist/docs/checkout/checkout-metadata.md +219 -0
- package/dist/docs/checkout/static-checkout-url.md +201 -0
- package/dist/docs/cli/commands.md +1 -1
- package/dist/docs/cli/environments.md +17 -9
- package/dist/docs/cli/kelviq-config.md +35 -1
- package/dist/docs/cli/overview.md +2 -0
- package/dist/docs/coustomers-management/overview.md +15 -19
- package/dist/docs/customer-portal/managing-payment-methods.md +30 -48
- package/dist/docs/frontend-integration/react-ui.md +51 -16
- package/dist/docs/getstarted/fees.md +45 -54
- package/dist/docs/getstarted/payment-security-and-seller-funds.md +98 -0
- package/dist/docs/getstarted/review-process.md +3 -3
- package/dist/docs/guides/agent-toolkit.md +143 -0
- package/dist/docs/guides/mcp-server.md +134 -63
- package/dist/docs/guides/migrate-from-cashfree.md +7 -0
- package/dist/docs/guides/sandbox.md +34 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +44 -18
- package/dist/docs/guides/subscription-integration.md +28 -4
- package/dist/docs/guides/webhooks.md +367 -6
- package/dist/docs/manifest.json +109 -4
- package/dist/docs/openapi.json +7411 -2648
- package/dist/docs/payouts/overview.md +30 -0
- package/dist/docs/payouts/transactions.md +50 -6
- package/dist/docs/product-catalog/create-a-feature.md +113 -0
- package/dist/docs/product-catalog/create-an-enterprise-plan.md +133 -0
- package/dist/docs/product-catalog/discounts.md +25 -12
- package/dist/docs/product-catalog/entitlements.md +53 -16
- package/dist/docs/product-catalog/free-and-trials.md +8 -4
- package/dist/docs/product-catalog/location-based-pricing.md +2 -0
- package/dist/docs/product-catalog/one-time-payments.md +4 -0
- package/dist/docs/product-catalog/pay-as-you-go.md +177 -0
- package/dist/docs/product-catalog/plans.md +14 -0
- package/dist/docs/product-catalog/products.md +5 -13
- package/dist/docs/product-catalog/seat-based-pricing.md +233 -0
- package/dist/docs/product-catalog/subscriptions.md +109 -12
- package/dist/docs/product-catalog/usage-alerts.md +257 -0
- package/dist/docs/product-catalog/usage-based-billing.md +49 -12
- package/dist/docs/quickstart/dashboard-setup.md +1 -1
- package/dist/docs/sales/abandoned-cart-recovery.md +64 -0
- package/dist/docs/sales/create-a-one-time-charge.md +144 -0
- package/dist/http/client.js +9 -2
- package/dist/http/client.js.map +1 -1
- package/dist/http/errors.d.ts +8 -0
- package/dist/http/errors.js +20 -0
- package/dist/http/errors.js.map +1 -1
- package/dist/prompts/index.d.ts +2 -0
- package/dist/prompts/index.js +107 -0
- package/dist/prompts/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +30 -0
- package/dist/schemas/kelviq.js +50 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +15 -3
- package/dist/server.js.map +1 -1
- package/dist/tools/checkout.js +2 -1
- package/dist/tools/checkout.js.map +1 -1
- package/dist/tools/customers.js +2 -0
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/docs.js +2 -0
- package/dist/tools/docs.js.map +1 -1
- package/dist/tools/entitlements.js +1 -0
- package/dist/tools/entitlements.js.map +1 -1
- package/dist/tools/features.js +4 -0
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/licenses.js +3 -0
- package/dist/tools/licenses.js.map +1 -1
- package/dist/tools/offerings.js +1 -0
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +4 -0
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plan-files.js +3 -0
- package/dist/tools/plan-files.js.map +1 -1
- package/dist/tools/plans.js +8 -0
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/portal.js +1 -0
- package/dist/tools/portal.js.map +1 -1
- package/dist/tools/product-files.js +2 -0
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +2 -0
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +5 -0
- package/dist/tools/products.js.map +1 -1
- package/dist/tools/promotions.js +1 -0
- package/dist/tools/promotions.js.map +1 -1
- package/dist/tools/subscriptions.js +5 -1
- package/dist/tools/subscriptions.js.map +1 -1
- package/dist/tools/usage.js +1 -0
- package/dist/tools/usage.js.map +1 -1
- package/package.json +1 -1
|
@@ -36,7 +36,7 @@ function App() {
|
|
|
36
36
|
return (
|
|
37
37
|
<KelviqProvider
|
|
38
38
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
39
|
-
|
|
39
|
+
productId="YOUR_PRODUCT_ID"
|
|
40
40
|
customerId="OPTIONAL_CUSTOMER_ID"
|
|
41
41
|
>
|
|
42
42
|
|
|
@@ -60,7 +60,7 @@ function App() {
|
|
|
60
60
|
return (
|
|
61
61
|
<KelviqProvider
|
|
62
62
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
63
|
-
|
|
63
|
+
productId="YOUR_PRODUCT_ID"
|
|
64
64
|
customerId="OPTIONAL_CUSTOMER_ID"
|
|
65
65
|
>
|
|
66
66
|
|
|
@@ -81,8 +81,8 @@ The top-level provider component that initializes the SDK and manages the global
|
|
|
81
81
|
|
|
82
82
|
| Prop | Type | Description |
|
|
83
83
|
|------|------|-------------|
|
|
84
|
-
| `accessToken` | `string` | Your kelviq
|
|
85
|
-
| `
|
|
84
|
+
| `accessToken` | `string` | Your kelviq access token |
|
|
85
|
+
| `productId` | `string` | The unique identifier of the product to display the offering for |
|
|
86
86
|
|
|
87
87
|
#### Optional Props
|
|
88
88
|
|
|
@@ -115,7 +115,8 @@ The main pricing table component that displays all plans and handles user intera
|
|
|
115
115
|
|
|
116
116
|
| Prop | Type | Default | Description |
|
|
117
117
|
|------|------|---------|-------------|
|
|
118
|
-
| `customStyles` | `PricingTableStyle` | `{}` |
|
|
118
|
+
| `customStyles` | `PricingTableStyle` | `{}` | Style overrides (colors, typography, layout). Any field you omit falls back to the SDK defaults. |
|
|
119
|
+
| `pricingOptions` | `Partial<PricingOptions>` | `DEFAULT_PRICING_OPTIONS` | Price-formatting options (decimals, currency symbol/code, localization). Partial objects are merged with the defaults. |
|
|
119
120
|
| `customActionButton` | `CustomActionButton` | `undefined` | Custom button component |
|
|
120
121
|
| `customCheckIcon` | `React.ReactNode` | `undefined` | Custom check icon |
|
|
121
122
|
| `customUnCheckIcon` | `React.ReactNode` | `undefined` | Custom uncheck icon |
|
|
@@ -181,7 +182,7 @@ Renders a list of pricing plans with billing period switching.
|
|
|
181
182
|
| Prop | Type | Required | Description |
|
|
182
183
|
|------|------|----------|-------------|
|
|
183
184
|
| `plans` | `OfferingPlan[]` | Yes | Array of plans to display |
|
|
184
|
-
| `
|
|
185
|
+
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
|
|
185
186
|
| `billingPeriods` | `BillingPeriod[]` | Yes | Available billing periods |
|
|
186
187
|
| `countryCode` | `string` | Yes | Country code for localization |
|
|
187
188
|
| `currencyCode` | `string` | Yes | Currency code (e.g., "USD") |
|
|
@@ -203,7 +204,7 @@ Displays a single pricing plan card.
|
|
|
203
204
|
| Prop | Type | Required | Description |
|
|
204
205
|
|------|------|----------|-------------|
|
|
205
206
|
| `plan` | `OfferingPlan` | Yes | Plan data to display |
|
|
206
|
-
| `
|
|
207
|
+
| `pricingOptions` | `PricingOptions` | Yes | Price-formatting options |
|
|
207
208
|
| `period` | `ChargePeriodEnum` | Yes | Current billing period |
|
|
208
209
|
| `countryCode` | `string` | Yes | Country code |
|
|
209
210
|
| `currencyCode` | `string` | Yes | Currency code |
|
|
@@ -253,9 +254,10 @@ Renders the features list for a plan.
|
|
|
253
254
|
| `customCheckIcon` | `React.ReactNode` | No | Custom check icon |
|
|
254
255
|
| `customUnCheckIcon` | `React.ReactNode` | No | Custom uncheck icon |
|
|
255
256
|
| `customTooltipIcon` | `React.ReactNode` | No | Custom tooltip icon |
|
|
256
|
-
| `descriptionTooltipEnabled` | `boolean` | No | Enable tooltips |
|
|
257
257
|
| `onUsageChange` | `(featureId: string, quantity: number) => void` | No | Usage change handler |
|
|
258
258
|
|
|
259
|
+
> Feature tooltips are controlled per-feature by the `displayTooltipDescription` flag on each feature in the offering data, configured in your kelviq dashboard — there is no global tooltip prop.
|
|
260
|
+
|
|
259
261
|
---
|
|
260
262
|
|
|
261
263
|
## 5. Data Types
|
|
@@ -316,6 +318,16 @@ interface PricingTableStyle {
|
|
|
316
318
|
typography: PricingTableTypographyConfig;
|
|
317
319
|
layout: PricingTableLayoutConfig;
|
|
318
320
|
}
|
|
321
|
+
|
|
322
|
+
// Price-formatting options (passed via the `pricingOptions` prop)
|
|
323
|
+
interface PricingOptions {
|
|
324
|
+
localization: boolean; // use the offering's locale/currency formatting
|
|
325
|
+
showDecimal: boolean; // show decimal places
|
|
326
|
+
minimumDecimalDigits: number; // minimum decimal places
|
|
327
|
+
maximumDecimalDigits: number; // maximum decimal places
|
|
328
|
+
showCurrencySymbol: boolean; // show the currency symbol (e.g. $)
|
|
329
|
+
showCurrencyCode: boolean; // show the currency code (e.g. USD)
|
|
330
|
+
}
|
|
319
331
|
```
|
|
320
332
|
|
|
321
333
|
### Color Configuration
|
|
@@ -371,6 +383,7 @@ interface PricingTableLayoutConfig {
|
|
|
371
383
|
maxWidth: number;
|
|
372
384
|
gap: number;
|
|
373
385
|
align: 'start' | 'center' | 'end';
|
|
386
|
+
tierSelectionType: 'switch' | 'tabs';
|
|
374
387
|
}
|
|
375
388
|
```
|
|
376
389
|
|
|
@@ -472,7 +485,28 @@ const customStyles: PricingTableStyle = {
|
|
|
472
485
|
};
|
|
473
486
|
```
|
|
474
487
|
|
|
475
|
-
### 6.3.
|
|
488
|
+
### 6.3. Price Formatting
|
|
489
|
+
|
|
490
|
+
How prices are formatted is configured entirely in the SDK via the `pricingOptions` prop. Pass only the fields you want to change — the rest fall back to `DEFAULT_PRICING_OPTIONS`:
|
|
491
|
+
|
|
492
|
+
```tsx
|
|
493
|
+
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
Defaults (`DEFAULT_PRICING_OPTIONS`):
|
|
497
|
+
|
|
498
|
+
```tsx
|
|
499
|
+
{
|
|
500
|
+
localization: true,
|
|
501
|
+
showDecimal: true,
|
|
502
|
+
minimumDecimalDigits: 0,
|
|
503
|
+
maximumDecimalDigits: 2,
|
|
504
|
+
showCurrencySymbol: true,
|
|
505
|
+
showCurrencyCode: false,
|
|
506
|
+
}
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
### 6.4. Custom Action Button
|
|
476
510
|
|
|
477
511
|
```tsx
|
|
478
512
|
const CustomButton: CustomActionButton = ({ onClick, children, plan, disabled }) => (
|
|
@@ -495,7 +529,7 @@ const CustomButton: CustomActionButton = ({ onClick, children, plan, disabled })
|
|
|
495
529
|
|
|
496
530
|
```
|
|
497
531
|
|
|
498
|
-
### 6.
|
|
532
|
+
### 6.5. noStyles Mode
|
|
499
533
|
|
|
500
534
|
For complete styling control, use the `noStyles` prop:
|
|
501
535
|
|
|
@@ -503,7 +537,7 @@ For complete styling control, use the `noStyles` prop:
|
|
|
503
537
|
|
|
504
538
|
```
|
|
505
539
|
|
|
506
|
-
### 6.
|
|
540
|
+
### 6.6. CSS Class Reference
|
|
507
541
|
|
|
508
542
|
The kelviq React UI components use consistent CSS class names that you can target for custom styling. All classes are prefixed with `kq-` to avoid naming conflicts.
|
|
509
543
|
|
|
@@ -598,7 +632,7 @@ The SDK automatically handles subscription updates:
|
|
|
598
632
|
```tsx
|
|
599
633
|
<KelviqProvider
|
|
600
634
|
accessToken="YOUR_TOKEN"
|
|
601
|
-
|
|
635
|
+
productId="YOUR_PRODUCT_ID"
|
|
602
636
|
apiConfig={{
|
|
603
637
|
onError: (error) => {
|
|
604
638
|
console.error('kelviq Error:', error);
|
|
@@ -678,7 +712,7 @@ const App: React.FC = () => {
|
|
|
678
712
|
|
|
679
713
|
<KelviqProvider
|
|
680
714
|
accessToken="your-access-token"
|
|
681
|
-
|
|
715
|
+
productId="your-product-id"
|
|
682
716
|
customerId="optional-customer-id"
|
|
683
717
|
checkoutSuccessUrl="https://yourapp.com/success"
|
|
684
718
|
apiConfig={{
|
|
@@ -703,6 +737,7 @@ export default App;
|
|
|
703
737
|
|
|
704
738
|
The SDK uses the following default API endpoints:
|
|
705
739
|
|
|
740
|
+
- **Product Offering API**: `https://api.kelviq.com/api/v1/monetization/product-offering/{productId}/`
|
|
706
741
|
- **Checkout API**: `https://api.kelviq.com/api/v1/checkout/`
|
|
707
742
|
- **Subscription API**: `https://api.kelviq.com/api/v1/subscriptions`
|
|
708
743
|
|
|
@@ -724,7 +759,7 @@ You can override these in the `apiConfig`:
|
|
|
724
759
|
|
|
725
760
|
### Common Issues
|
|
726
761
|
|
|
727
|
-
1. **Loading State**: Ensure your `accessToken` and `
|
|
762
|
+
1. **Loading State**: Ensure your `accessToken` and `productId` are correct
|
|
728
763
|
2. **Styling Issues**: Check CSS variable overrides and custom styles
|
|
729
764
|
3. **API Errors**: Verify API endpoints and network connectivity
|
|
730
765
|
4. **TypeScript Errors**: Ensure all required props are provided
|
|
@@ -739,7 +774,7 @@ Enable console logging for debugging:
|
|
|
739
774
|
onError: (error) => {
|
|
740
775
|
console.log('kelviq Debug:', {
|
|
741
776
|
error: error.message,
|
|
742
|
-
|
|
777
|
+
productId: 'your-product-id',
|
|
743
778
|
timestamp: new Date().toISOString()
|
|
744
779
|
});
|
|
745
780
|
}
|
|
@@ -755,7 +790,7 @@ If you want to use the sandbox, you need to set the `environment` option to `san
|
|
|
755
790
|
```tsx
|
|
756
791
|
<KelviqProvider
|
|
757
792
|
accessToken="YOUR_ACCESS_TOKEN"
|
|
758
|
-
|
|
793
|
+
productId="YOUR_PRODUCT_ID"
|
|
759
794
|
environment="sandbox">
|
|
760
795
|
|
|
761
796
|
</KelviqProvider>
|
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
title: "Fees"
|
|
3
3
|
slug: "getstarted/fees"
|
|
4
4
|
section: "getstarted"
|
|
5
|
-
description: "Kelviq's
|
|
5
|
+
description: "Understand Kelviq's transaction fees and additional charges"
|
|
6
6
|
---
|
|
7
|
-
Kelviq operates as a [Merchant of Record](/getstarted/merchant-of-record), handling payments, tax compliance, and global selling on your behalf.
|
|
7
|
+
Kelviq operates as a [Merchant of Record](/getstarted/merchant-of-record), handling payments, tax compliance, and global selling on your behalf. You pay a transaction fee when a payment succeeds. There are no setup fees, monthly fees, or minimum transaction requirements.
|
|
8
8
|
|
|
9
|
-
## What's
|
|
9
|
+
## What's included
|
|
10
10
|
|
|
11
11
|
Your transaction fee covers everything you need to sell globally:
|
|
12
12
|
|
|
@@ -21,75 +21,66 @@ Your transaction fee covers everything you need to sell globally:
|
|
|
21
21
|
- Feature and entitlement management
|
|
22
22
|
- Customer billing portal
|
|
23
23
|
|
|
24
|
-
## Transaction
|
|
24
|
+
## Transaction fees
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Every successful payment starts with a base fee. The base rate changes after your organization processes $5,000 in total sales volume. A recurring charge or international card can add another percentage to the same transaction.
|
|
27
27
|
|
|
28
|
-
| Fee
|
|
29
|
-
|
|
30
|
-
| Base fee |
|
|
31
|
-
|
|
|
32
|
-
| Recurring billing | +0.7% | Subscription and
|
|
28
|
+
| Fee component | Rate | When it applies |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| Base fee, up to $5,000 in total volume | 2.9% + $0.40 | Successful transactions processed before your organization reaches $5,000 in total sales |
|
|
31
|
+
| Base fee, after $5,000 in total volume | 3.5% + $0.40 | Subsequent successful transactions after your organization reaches $5,000 in total sales |
|
|
32
|
+
| Recurring billing | +0.7% | Subscription payments and renewals |
|
|
33
|
+
| International card | +1.5% | Cards issued outside the United States |
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
The recurring and international-card percentages are added to the applicable base rate. The fixed $0.40 is charged once per successful transaction.
|
|
35
36
|
|
|
36
|
-
|
|
37
|
+
### How the $5,000 threshold works
|
|
37
38
|
|
|
38
|
-
|
|
39
|
+
The threshold is based on your organization's cumulative processed sales volume, not the number of payments or the volume for a single month. You pay 2.9% + $0.40 on transactions processed before reaching $5,000. After your total processed volume reaches $5,000, subsequent transactions use the 3.5% + $0.40 base rate.
|
|
39
40
|
|
|
40
|
-
|
|
41
|
+
The rate change does not alter fees on transactions that were already processed.
|
|
41
42
|
|
|
42
|
-
|
|
43
|
-
|-----------|-------------|--------|
|
|
44
|
-
| Base fee | $100 × 3.5% | $3.50 |
|
|
45
|
-
| Fixed fee | — | $0.40 |
|
|
46
|
-
| **Total fee** | | **$3.90** |
|
|
43
|
+
## All fee combinations
|
|
47
44
|
|
|
48
|
-
|
|
49
|
-
|
|
45
|
+
The additional percentages stack when a charge is both recurring and paid with an international card.
|
|
50
46
|
|
|
51
|
-
|
|
47
|
+
| Transaction type | Up to $5,000 in total volume | After $5,000 in total volume |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| One-time payment, domestic card | 2.9% + $0.40 | 3.5% + $0.40 |
|
|
50
|
+
| One-time payment, international card | 4.4% + $0.40 | 5.0% + $0.40 |
|
|
51
|
+
| Subscription, domestic card | 3.6% + $0.40 | 4.2% + $0.40 |
|
|
52
|
+
| Subscription, international card | 5.1% + $0.40 | 5.7% + $0.40 |
|
|
52
53
|
|
|
53
|
-
|
|
54
|
+
### Example fees on a $100 charge
|
|
54
55
|
|
|
55
|
-
|
|
56
|
-
|-----------|-------------|--------|
|
|
57
|
-
| Base fee | $100 × 3.5% | $3.50 |
|
|
58
|
-
| Fixed fee | — | $0.40 |
|
|
59
|
-
| International | $100 × 1.5% | $1.50 |
|
|
60
|
-
| **Total fee** | | **$5.40** |
|
|
56
|
+
This example uses a $100 gross charge. If the payment includes tax, the gross amount is the full amount charged to the customer.
|
|
61
57
|
|
|
62
|
-
|
|
63
|
-
|
|
58
|
+
| Transaction type | Fee before the $5,000 threshold | Fee after the $5,000 threshold |
|
|
59
|
+
| --- | ---: | ---: |
|
|
60
|
+
| One-time payment, domestic card | $3.30 | $3.90 |
|
|
61
|
+
| One-time payment, international card | $4.80 | $5.40 |
|
|
62
|
+
| Subscription, domestic card | $4.00 | $4.60 |
|
|
63
|
+
| Subscription, international card | $5.50 | $6.10 |
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
## How fees appear in Transactions
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
The **Fee** column under **Payouts → Transactions** shows the total fee deducted from a payment. It combines the applicable base rate, recurring fee, and international-card fee into one amount. Tax is shown separately.
|
|
68
68
|
|
|
69
|
-
|
|
70
|
-
|-----------|-------------|--------|
|
|
71
|
-
| Base fee | $50 × 3.5% | $1.75 |
|
|
72
|
-
| Fixed fee | — | $0.40 |
|
|
73
|
-
| Recurring | $50 × 0.7% | $0.35 |
|
|
74
|
-
| **Total fee** | | **$2.50** |
|
|
69
|
+
For a successful transaction:
|
|
75
70
|
|
|
76
|
-
|
|
77
|
-
|
|
71
|
+
```text
|
|
72
|
+
Net = Gross - Fee - Tax
|
|
73
|
+
```
|
|
78
74
|
|
|
79
|
-
|
|
75
|
+
[Learn how to read the Transactions page →](/payouts/transactions)
|
|
80
76
|
|
|
81
|
-
|
|
77
|
+
## Payout fees
|
|
82
78
|
|
|
83
|
-
|
|
84
|
-
|-----------|-------------|--------|
|
|
85
|
-
| Base fee | $50 × 3.5% | $1.75 |
|
|
86
|
-
| Fixed fee | — | $0.40 |
|
|
87
|
-
| International | $50 × 1.5% | $0.75 |
|
|
88
|
-
| Recurring | $50 × 0.7% | $0.35 |
|
|
89
|
-
| **Total fee** | | **$3.25** |
|
|
79
|
+
Currently, Kelviq is bearing the payout fee.
|
|
90
80
|
|
|
91
|
-
|
|
92
|
-
|
|
81
|
+
Transaction fees and payout fees happen at different stages. The transaction fee is deducted when a customer pays. A payout fee would typically apply later when funds are sent to your bank account or eligible debit card, but Kelviq currently covers this cost.
|
|
82
|
+
|
|
83
|
+
[Learn how Kelviq payouts work →](/payouts/overview)
|
|
93
84
|
|
|
94
85
|
## Refunds
|
|
95
86
|
|
|
@@ -102,7 +93,7 @@ When you issue a refund to a customer, the original transaction fee is **retaine
|
|
|
102
93
|
|
|
103
94
|
Our payment partners charge non-refundable processing fees on the original transaction. We pass this cost structure through to maintain transparent pricing.
|
|
104
95
|
|
|
105
|
-
## Disputes
|
|
96
|
+
## Disputes and chargebacks
|
|
106
97
|
|
|
107
98
|
When a customer disputes a charge with their bank, a **$15 fee** applies regardless of the dispute outcome.
|
|
108
99
|
|
|
@@ -111,7 +102,7 @@ When a customer disputes a charge with their bank, a **$15 fee** applies regardl
|
|
|
111
102
|
| You win | $15 | Returned to you |
|
|
112
103
|
| You lose | $15 | Refunded to customer |
|
|
113
104
|
|
|
114
|
-
### Reducing
|
|
105
|
+
### Reducing disputes
|
|
115
106
|
|
|
116
107
|
|
|
117
108
|
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Payment security and seller funds"
|
|
3
|
+
slug: "getstarted/payment-security-and-seller-funds"
|
|
4
|
+
section: "getstarted"
|
|
5
|
+
description: "How Kelviq protects card details, routes payments through Stripe, and handles payouts, account reviews, and migrations"
|
|
6
|
+
---
|
|
7
|
+
When a customer buys through Kelviq Checkout, Kelviq is the Merchant of Record and Stripe processes the payment. The customer's raw card details go directly to Stripe through secure payment fields; they are not passed to Kelviq or your connected account. Stripe also provides the connected account used for your payouts. Here is how payment data, money, and subscription records move at each stage.
|
|
8
|
+
|
|
9
|
+
This page is an operational overview. If it conflicts with the [Seller Agreement](/legal/master-service-agreement), the agreement controls.
|
|
10
|
+
|
|
11
|
+
## How does a payment move?
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
Kelviq Checkout uses [Stripe Elements](https://docs.stripe.com/payments/elements). Stripe tokenizes sensitive payment details in the browser, so the full card number and CVC do not pass through or get stored on Kelviq's servers.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
The charge and its PaymentIntent are created on Kelviq's Stripe platform account because Kelviq is the Merchant of Record.
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
Kelviq accounts for applicable taxes, platform fees, refunds, and other adjustments before calculating your net revenue.
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
Kelviq creates a separate transfer to your Stripe Express connected account. The funds appear there after Stripe makes them available.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
You can withdraw cleared funds to the bank account attached to your connected account.
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
Kelviq uses Stripe Connect's **separate charges and transfers** model. It does not use direct charges or destination charges. See the [full payment flow](/legal/payment-flow-diagram) for the technical breakdown.
|
|
39
|
+
|
|
40
|
+
## Who handles the card details?
|
|
41
|
+
|
|
42
|
+
The checkout may carry Kelviq's design, but Stripe provides the sensitive payment fields. Stripe.js tokenizes the details inside those fields and returns identifiers Kelviq can use to complete the payment. Kelviq receives the payment result, not the customer's full card number or CVC.
|
|
43
|
+
|
|
44
|
+
Stripe can also request 3D Secure authentication when it is required by the card issuer or recommended for fraud prevention. This adds an identity check without exposing the customer's card details to Kelviq.
|
|
45
|
+
|
|
46
|
+
Banks can still decline or reverse a payment, customers can open disputes, and Stripe or a card network can request a review. Kelviq handles those events as the Merchant of Record.
|
|
47
|
+
|
|
48
|
+
## Where does the money actually sit?
|
|
49
|
+
|
|
50
|
+
During processing, the money appears in Stripe balances. It first appears in Kelviq's Stripe platform balance. After the separate transfer, your share appears in your Stripe connected-account balance. Stripe then sends the payout to your registered bank account.
|
|
51
|
+
|
|
52
|
+
A Kelviq payout balance is not a bank deposit, escrow account, or insured investment. It represents amounts due under the Seller Agreement and can change because of refunds, chargebacks, fees, currency conversion, or a valid reserve.
|
|
53
|
+
|
|
54
|
+
You can track this flow in two places:
|
|
55
|
+
|
|
56
|
+
- The Kelviq **Payouts** dashboard shows processing funds, cleared funds, withdrawals, and payout history.
|
|
57
|
+
- Your Stripe connected-account details show the verified business and bank account used for payouts.
|
|
58
|
+
|
|
59
|
+
Read [Payouts](/payouts/overview) for the dashboard workflow.
|
|
60
|
+
|
|
61
|
+
## What protects my funds if Kelviq closes my account?
|
|
62
|
+
|
|
63
|
+
The Seller Agreement sets out Kelviq's payout obligations and when a payout can be delayed or reserved:
|
|
64
|
+
|
|
65
|
+
- Completed transactions move to your available balance after processing.
|
|
66
|
+
- Final payouts remain due if Kelviq ends the service, subject to open disputes and a permitted reserve.
|
|
67
|
+
- A reserve must have a stated amount or percentage and an expected duration.
|
|
68
|
+
- A post-termination reserve can remain in place for up to 180 days to cover refunds, chargebacks, or other transaction liabilities.
|
|
69
|
+
|
|
70
|
+
This is not a guarantee that nothing can go wrong. A processor failure, bank delay, dispute, compliance action, or insolvency can still affect the timing or recovery of funds. What you do have is a written payment flow, transaction records, and contractual payout terms against which you can check Kelviq's handling of your money. Review [Payout Terms](/legal/master-service-agreement#7-payout-terms) and [Reserves and Holdbacks](/legal/master-service-agreement#8-reserves-and-holdbacks) for the controlling language.
|
|
71
|
+
|
|
72
|
+
## How much notice will I get before a suspension?
|
|
73
|
+
|
|
74
|
+
There is no single advance-notice period for every suspension, including every non-fraud suspension. Kelviq may need to act quickly because of suspected fraud, prohibited activity, failed verification, a legal requirement, a payment-network instruction, or a restriction on the connected Stripe account.
|
|
75
|
+
|
|
76
|
+
The 30-day notice in the Seller Agreement applies when Kelviq terminates an account for convenience. It does not apply to the grounds for immediate termination listed in that agreement. If you believe a policy suspension or termination was made in error, you can appeal it. Kelviq responds to appeals within 10 business days under the [Acceptable Use Policy](/legal/approved-prohibited-policy#83-appeal-process).
|
|
77
|
+
|
|
78
|
+
### Will my customers' subscriptions cancel immediately?
|
|
79
|
+
|
|
80
|
+
Not in every case. A suspension and a subscription cancellation are separate actions. However, Kelviq may need to block checkout or future renewals, depending on why the account was restricted. The Seller Agreement does not promise uninterrupted subscription collection during a suspension. If a notice does not clearly say which functions are affected, contact [support@kelviq.com](mailto:support@kelviq.com) before making changes for your customers.
|
|
81
|
+
|
|
82
|
+
## Where do the Stripe Customer and Subscription records live?
|
|
83
|
+
|
|
84
|
+
Kelviq manages the buyer-facing Stripe Customer, PaymentIntent, invoice, and Subscription records on its Stripe platform account. Your Stripe Express connected account receives transfers and payouts; it does not receive an independent copy of every platform billing object.
|
|
85
|
+
|
|
86
|
+
An ID such as `cus_...` or `sub_...` points to an object inside the Stripe account where it was created. It cannot simply be reassigned to another Stripe account. Under the [Seller Agreement](/legal/master-service-agreement#111-buyer-data), Kelviq controls buyer payment and transaction data in its role as Merchant of Record. You still own your product and content, and Kelviq provides the buyer information needed for fulfillment and customer support.
|
|
87
|
+
|
|
88
|
+
## Can I move to another provider?
|
|
89
|
+
|
|
90
|
+
A billing migration is possible in some cases, but it is not an automatic account transfer. Contact [support@kelviq.com](mailto:support@kelviq.com) before closing your Kelviq account or disconnecting Stripe. Kelviq will review the request with Stripe and the receiving provider, then explain what can be transferred.
|
|
91
|
+
|
|
92
|
+
Stripe supports secure exports of eligible card data to a PCI DSS Level 1 payment processor. Some credentials, including cards saved through Link, cannot be exported. Subscription records and payment history also need to be mapped or recreated in the new billing system; moving card data alone does not move an active subscription.
|
|
93
|
+
|
|
94
|
+
Migration scope and timing depend on the receiving provider, Stripe's requirements, applicable privacy rules, and any unresolved refunds, disputes, or reserves. See [Stripe's payment-data export process](https://docs.stripe.com/get-started/data-migrations/pan-export) for the processor-level requirements.
|
|
95
|
+
|
|
96
|
+
## Questions about your account
|
|
97
|
+
|
|
98
|
+
For an account-specific explanation of a payout, reserve, suspension, or migration, email [support@kelviq.com](mailto:support@kelviq.com). Include your Kelviq business name and the relevant transaction, payout, or subscription IDs, but never send a full card number or CVC.
|
|
@@ -132,11 +132,11 @@ There are two steps to complete before you can start accepting real payments:
|
|
|
132
132
|
|
|
133
133
|
### Step 1: Business Verification
|
|
134
134
|
|
|
135
|
-
|
|
135
|
+
Open **Settings → Business details** in the Kelviq dashboard. You can also continue from the business-verification prompt shown during onboarding.
|
|
136
136
|
|
|
137
|
-
<img src="/images/review-process/business-verification-prompt.png" alt="Business
|
|
137
|
+
<img src="/images/review-process/business-verification-prompt.png" alt="Business verification prompt shown during onboarding" />
|
|
138
138
|
|
|
139
|
-
Fill in your business details and click **Submit for review** when you're done.
|
|
139
|
+
Fill in your business details and click **Submit for review** when you're done. Kelviq places the country from your organization profile first in the country selector to make it easier to find. Review the country before submitting the form.
|
|
140
140
|
|
|
141
141
|
<img src="/images/review-process/business-details-form.png" alt="Business details form" />
|
|
142
142
|
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Agent Toolkit"
|
|
3
|
+
slug: "guides/agent-toolkit"
|
|
4
|
+
section: "guides"
|
|
5
|
+
description: "Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents."
|
|
6
|
+
---
|
|
7
|
+
The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
|
|
8
|
+
|
|
9
|
+
Skills are the missing half of tool access. The MCP server gives your agent 45 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
|
|
10
|
+
|
|
11
|
+
**The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Install — Claude Code
|
|
16
|
+
|
|
17
|
+
Two commands, in any Claude Code session:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
/plugin marketplace add kelviq/agent-toolkit
|
|
21
|
+
/plugin install kelviq@kelviq
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all five skills are available immediately.
|
|
25
|
+
|
|
26
|
+
The server reads your API keys from environment variables. It uses your **sandbox** environment unless `KELVIQ_ENV=production`, so start with sandbox keys. Set them in your shell profile before starting Claude Code:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
export KELVIQ_SERVER_API_KEY="<your-sandbox-server-key>"
|
|
30
|
+
export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for promotion_get
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
|
|
34
|
+
|
|
35
|
+
**Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 45 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
|
|
36
|
+
|
|
37
|
+
No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Install — any other agent
|
|
42
|
+
|
|
43
|
+
The five skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx skills add kelviq/agent-toolkit
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Add `--skill <name>` to install a single skill instead of the full set:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx skills add kelviq/agent-toolkit --skill setup-payments
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
This path installs **skills only** — it doesn't configure an MCP server for you. Each skill starts with a short Setup section showing the `.mcp.json` snippet to connect `@kelviq/mcp-server` on your agent; see the [MCP server guide](/guides/mcp-server) for client-specific instructions.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## The five skills
|
|
60
|
+
|
|
61
|
+
| Skill | What it teaches |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `kelviq` | The hub. Connecting any agent to Kelviq, the ground rules (docs-first, error handling, confirm-before-destructive), the concept model (identifiers vs UUIDs, feature types, plan lifecycle, environments), and routing to the right skill or prompt for the task. |
|
|
64
|
+
| `pricing-plans` | Designing and publishing the catalog: products, features, plans, entitlements, the DRAFT → publish lifecycle, and customer-migration decisions on publish. |
|
|
65
|
+
| `setup-payments` | Selling plans and managing subscribers: checkout sessions, subscriptions, trials, upgrades, cancellation, and authenticated customer portal links. |
|
|
66
|
+
| `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for metered features, and the license key lifecycle. |
|
|
67
|
+
| `pricing-as-code` | The [Kelviq CLI](/cli/overview) workflow: pull the live catalog into `kelviq.config.ts`, edit in git, preview the diff, apply, and promote sandbox to production. |
|
|
68
|
+
|
|
69
|
+
### `kelviq` — the hub
|
|
70
|
+
|
|
71
|
+
Loads for any Kelviq task that doesn't match a more specific skill. It carries the knowledge every other skill assumes:
|
|
72
|
+
|
|
73
|
+
- **Identifiers vs UUIDs** — when an endpoint wants the URL-safe `identifier` and when it wants the UUID, and how to resolve one from the other.
|
|
74
|
+
- **Feature types** — `BOOLEAN` (flag), `CUSTOMIZABLE` (numeric quantity), `METER` (usage-tracked), and how entitlement shapes differ per type.
|
|
75
|
+
- **Plan lifecycle** — plans are created in DRAFT and invisible until published; updating a published plan creates a new draft.
|
|
76
|
+
- **Environments** — sandbox by default, `KELVIQ_ENV=production` only for live data, and why "not found" errors often mean "right key, wrong environment".
|
|
77
|
+
- **A customer-access diagnosis flow** — comparing what a customer *has* (`entitlements_get`), what they *bought* (`subscription_list`), and what their plan *grants* (`plan_entitlements_list`).
|
|
78
|
+
|
|
79
|
+
### `pricing-plans`
|
|
80
|
+
|
|
81
|
+
The golden path from empty account to published plan: create the product, create the features, create the plan (in DRAFT), attach entitlements, set prices, publish, verify. Includes the two decisions agents most often get wrong: whether to migrate existing customers on publish (`updateFeatures` / `updatePricing` — always a deliberate, confirmed choice), and where prices are managed (the dashboard or the CLI — the MCP server deliberately has no price-write tool).
|
|
82
|
+
|
|
83
|
+
### `setup-payments`
|
|
84
|
+
|
|
85
|
+
Checkout-first selling. The skill teaches that `checkout_create_session` is the default way to charge a customer — direct subscription creation charges off-session and is only enabled for some organizations — plus trial handling (`trialEnd`), safe plan changes (`paymentBehavior`), cancellation types, and the customer portal (always the signed URL from `portal_session_create`; a bare portal URL doesn't authenticate).
|
|
86
|
+
|
|
87
|
+
### `usage-based-billing`
|
|
88
|
+
|
|
89
|
+
Runtime enforcement. Entitlement checks via the edge-served `entitlements_get` (built to be cheap enough to call on the request path), the difference between `SET` and `DELTA` usage reporting — and why a blindly retried `DELTA` double-counts — plus license key activation, validation, and deactivation with `instanceId` handling.
|
|
90
|
+
|
|
91
|
+
### `pricing-as-code`
|
|
92
|
+
|
|
93
|
+
Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `kelviq.config.ts` in a branch → `kelviq push --dry-run` → review → apply → `kelviq promote` from sandbox to production. The skill has a built-in safety rule: an agent may run dry-runs and show you diffs freely, but **applying a real change always requires your explicit approval** — it will never chain a dry-run into an unattended `--yes`.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Skills, prompts, and tools — how they fit
|
|
98
|
+
|
|
99
|
+
The toolkit layers three things, each doing what it's best at:
|
|
100
|
+
|
|
101
|
+
1. **Tools** (from the MCP server) do the work — 45 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
|
|
102
|
+
2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
|
|
103
|
+
3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
|
|
104
|
+
|
|
105
|
+
Deep reference detail (field lists, price shapes, config schemas) intentionally lives in none of these — the skills direct the agent to `docs_search` / `docs_read`, so answers always come from the current documentation.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Sandbox and production
|
|
110
|
+
|
|
111
|
+
The bundled server uses your **sandbox** environment unless you set `KELVIQ_ENV=production` — separate data, separate keys, nothing crosses between them. Build and test in sandbox, and switch to production (with production API keys) only when you want the agent to work with live data. See the [sandbox guide](/guides/sandbox) for details.
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
export KELVIQ_ENV="production"
|
|
115
|
+
export KELVIQ_SERVER_API_KEY="<your-production-server-key>"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Updating
|
|
121
|
+
|
|
122
|
+
- **MCP server**: nothing to do. The toolkit runs `npx -y @kelviq/mcp-server@latest`, which checks for the newest published version each time the server starts.
|
|
123
|
+
- **Skills** (Claude Code): `/plugin marketplace update kelviq` pulls the latest marketplace content.
|
|
124
|
+
- **Skills** (other agents): re-run `npx skills add kelviq/agent-toolkit`.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Troubleshooting
|
|
129
|
+
|
|
130
|
+
**`kelviq:` tools aren't available** — on Claude Code, check `/mcp`; if the server isn't listed, reinstall the plugin. On other agents, the skills-only install doesn't include the server — follow the Setup section in any installed skill or the [MCP server guide](/guides/mcp-server).
|
|
131
|
+
|
|
132
|
+
**`Configuration error` from API tools** — `KELVIQ_SERVER_API_KEY` isn't visible to the process that launched your agent. Set it in your shell profile (not just the current terminal) and restart the agent.
|
|
133
|
+
|
|
134
|
+
**"Not found" on an identifier you can see in the dashboard** — your key and `KELVIQ_ENV` are probably pointing at the other environment. Sandbox and production are fully separate; a key only works against its own environment.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Related
|
|
139
|
+
|
|
140
|
+
- [MCP server guide](/guides/mcp-server) — manual per-client setup, full tool list, architecture
|
|
141
|
+
- [Kelviq CLI](/cli/overview) — the pricing-as-code workflow the `pricing-as-code` skill teaches
|
|
142
|
+
- [Sandbox](/guides/sandbox) — test environment setup
|
|
143
|
+
- [github.com/kelviq/agent-toolkit](https://github.com/kelviq/agent-toolkit) — the toolkit source
|