@kelviq/mcp-server 0.4.0 → 1.1.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 +43 -27
- package/dist/config.d.ts +4 -0
- package/dist/config.js +30 -9
- package/dist/config.js.map +1 -1
- package/dist/docs/README.md +16 -0
- 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 +23 -0
- package/dist/docs/changelog/node-sdk.md +124 -0
- package/dist/docs/changelog/python-sdk.md +135 -0
- package/dist/docs/changelog.md +3968 -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 +138 -35
- 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 +98 -56
- 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/schemas/kelviq.d.ts +199 -0
- package/dist/schemas/kelviq.js +173 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +11 -1
- package/dist/server.js.map +1 -1
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +74 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +4 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- package/package.json +1 -1
|
@@ -29,6 +29,23 @@ Your signing secret is shown only once. If you lose it, you must regenerate it f
|
|
|
29
29
|
|
|
30
30
|
---
|
|
31
31
|
|
|
32
|
+
## Inspect and resend deliveries
|
|
33
|
+
|
|
34
|
+
Open **Settings → Webhooks** and select an endpoint to view its delivery logs. Each delivery shows the event type, status, response code, and response body.
|
|
35
|
+
|
|
36
|
+
To retry a delivery:
|
|
37
|
+
|
|
38
|
+
1. Fix the endpoint or deployment issue that caused the delivery to fail.
|
|
39
|
+
2. Open the failed delivery in the webhook logs.
|
|
40
|
+
3. Click **Resend**.
|
|
41
|
+
4. Review the new delivery attempt and its response.
|
|
42
|
+
|
|
43
|
+
Kelviq also retries failed deliveries automatically. A manual resend is useful when the endpoint is working again and you want to retry immediately.
|
|
44
|
+
|
|
45
|
+
Automatic retries and manual resends can deliver the same event more than once. Process webhooks idempotently using the event `id` or the `webhook-id` header.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
32
49
|
## Event Types
|
|
33
50
|
|
|
34
51
|
| Event | Description |
|
|
@@ -40,14 +57,82 @@ Your signing secret is shown only once. If you lose it, you must regenerate it f
|
|
|
40
57
|
| `order.updated` | An existing order was updated. |
|
|
41
58
|
| `order.refunded` | A full or partial refund was issued against an order. |
|
|
42
59
|
| `subscription.created` | A new subscription was activated for a customer. |
|
|
43
|
-
| `subscription.updated` | A subscription's details were modified. |
|
|
44
|
-
| `subscription.cancelled` | A subscription
|
|
60
|
+
| `subscription.updated` | A subscription's details were modified — including when a cancellation is scheduled for the end of the current period (status stays active; `end_date` is set). |
|
|
61
|
+
| `subscription.cancelled` | A subscription actually reached cancelled status. For a period-end cancellation, this fires later, when the period ends — not at the moment it was scheduled. |
|
|
45
62
|
| `subscription.plan_changed` | A subscription was moved to a different plan. |
|
|
63
|
+
| `subscription.trial_will_end` | A subscription's trial period is ending soon. |
|
|
46
64
|
| `feature.usage_alert` | A customer's feature usage crossed a configured threshold. |
|
|
47
65
|
| `invoice.created` | A new invoice was generated. |
|
|
48
66
|
| `invoice.paid` | An invoice was paid and funds were collected. |
|
|
67
|
+
| `invoice.payment_failed` | A subscription invoice payment failed or requires customer action. |
|
|
49
68
|
| `refund.created` | A refund was initiated. |
|
|
50
69
|
| `refund.updated` | A refund's status changed (e.g., from pending to completed). |
|
|
70
|
+
| `payment_method.created` | A new payment method was added for a customer. |
|
|
71
|
+
| `payment_method.updated` | A payment method's status or default state changed. |
|
|
72
|
+
| `payment_method.deleted` | A payment method was removed from a customer. |
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Checkout, subscription, and payment lifecycle
|
|
77
|
+
|
|
78
|
+
### Checkout and subscription creation
|
|
79
|
+
|
|
80
|
+
`checkout.completed` confirms that checkout finished successfully, but it does not include `subscription_id`. Kelviq creates the subscription after checkout and sends its ID in `subscription.created`.
|
|
81
|
+
|
|
82
|
+
Use your customer identifier or checkout `metadata` to correlate the two events. See [Add metadata to checkout](/checkout/checkout-metadata) for request and webhook examples. Do not treat the checkout redirect as proof that a subscription has been created.
|
|
83
|
+
|
|
84
|
+
### Successful invoice payments
|
|
85
|
+
|
|
86
|
+
Kelviq sends `invoice.paid` whenever an invoice is paid, including invoices that are created directly with a `PAID` status. Use this event for payment-driven work such as recording revenue, starting an asynchronous provisioning job, or notifying an internal system.
|
|
87
|
+
|
|
88
|
+
For request-time access checks, query the customer's current entitlements instead of relying on a local webhook-derived subscription state.
|
|
89
|
+
|
|
90
|
+
### Failed invoice payments
|
|
91
|
+
|
|
92
|
+
Kelviq sends `invoice.payment_failed` when a subscription invoice payment fails or requires customer action. Use `data.object.subscription_id` and the embedded `customer` to identify the affected account. The invoice `status` is `PAYMENT_FAILED` for a failed attempt and can remain `OPEN` when the payment requires customer action.
|
|
93
|
+
|
|
94
|
+
This event can be followed by `invoice.paid` if the customer completes authentication or a later retry succeeds. Handle both events idempotently and treat the latest invoice and subscription state as authoritative.
|
|
95
|
+
|
|
96
|
+
### Subscription end dates
|
|
97
|
+
|
|
98
|
+
Subscription webhook objects include `end_date` inside `data.object`. Kelviq sets the field when a subscription has been cancelled or is scheduled to cancel on a future date. Otherwise, the value is `null`.
|
|
99
|
+
|
|
100
|
+
Use `end_date` for the subscription's scheduled or final end. `billing_period_end_time` describes the current billing period instead and should not be treated as the subscription's cancellation date.
|
|
101
|
+
|
|
102
|
+
### Failed renewal payments
|
|
103
|
+
|
|
104
|
+
Kelviq does not currently send a separate `payment.failed` event. For a failed card renewal:
|
|
105
|
+
|
|
106
|
+
1. The subscription moves to `past_due`.
|
|
107
|
+
2. Kelviq emails the customer a payment link.
|
|
108
|
+
3. Kelviq sends `subscription.updated` with the new subscription state.
|
|
109
|
+
4. Kelviq retries collection up to eight times over 14 days.
|
|
110
|
+
5. If all recovery attempts fail, Kelviq cancels the subscription and sends `subscription.cancelled`.
|
|
111
|
+
|
|
112
|
+
Do not remove access when you receive the first `subscription.updated` with `past_due` unless that is your own policy. Use the final subscription status or a live entitlement check to decide when access should end.
|
|
113
|
+
|
|
114
|
+
The retry window applies only to card payments. Kelviq does not retry a failed non-card renewal; the subscription is cancelled after the failure.
|
|
115
|
+
|
|
116
|
+
### Billing period field names
|
|
117
|
+
|
|
118
|
+
Subscription payloads use `billing_period_start_time` and `billing_period_end_time`. Match these names exactly when parsing dates. They describe the current billing period; use `end_date` for the subscription's scheduled or final end.
|
|
119
|
+
|
|
120
|
+
### Plan changes
|
|
121
|
+
|
|
122
|
+
By default, Kelviq applies a plan change immediately, charges any prorated difference, and sends `subscription.plan_changed`. After the generated invoice is paid, Kelviq sends the related order and invoice events.
|
|
123
|
+
|
|
124
|
+
If you update a subscription with `paymentBehavior: "activate_on_payment"`, the existing subscription remains `active` while payment is pending. A payment method that requires customer action leaves the updated subscription in `incomplete`. After payment succeeds, the updated subscription becomes `active` and the previous subscription becomes `superseded`. If an immediate charge fails, or the customer does not complete payment before expiry, the updated subscription becomes `incomplete_expired` and the existing subscription remains active.
|
|
125
|
+
|
|
126
|
+
Do not provision the new plan from the update API response alone. Read the latest subscription status or query the customer's current entitlements before changing access.
|
|
127
|
+
|
|
128
|
+
### Partial and full refunds
|
|
129
|
+
|
|
130
|
+
`order.refunded` identifies whether the order is partially or fully refunded through its `status`:
|
|
131
|
+
|
|
132
|
+
* `PARTIAL_REFUND` for a partial refund
|
|
133
|
+
* `REFUNDED` for a full refund
|
|
134
|
+
|
|
135
|
+
The `order.refunded` payload does not include the refunded amount. Read `amount` or `amount_units` from `refund.created` and `refund.updated` when you need the exact value.
|
|
51
136
|
|
|
52
137
|
---
|
|
53
138
|
|
|
@@ -384,6 +469,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
384
469
|
"end_date": null,
|
|
385
470
|
"billing_period_start_time": "2026-03-11T05:25:33Z",
|
|
386
471
|
"billing_period_end_time": "2026-04-10T06:28:58Z",
|
|
472
|
+
"trial_start": "2026-03-11T05:25:33Z",
|
|
473
|
+
"trial_end": "2026-03-25T05:25:33Z",
|
|
387
474
|
"customer": {
|
|
388
475
|
"id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
|
|
389
476
|
"name": "Geo Jacob",
|
|
@@ -450,6 +537,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
450
537
|
},
|
|
451
538
|
"billing_period_start_time": "2026-04-02T05:04:43Z",
|
|
452
539
|
"billing_period_end_time": "2026-05-02T05:04:43Z",
|
|
540
|
+
"trial_start": "2026-04-02T05:04:43Z",
|
|
541
|
+
"trial_end": "2026-04-16T05:04:43Z",
|
|
453
542
|
"created_on": "2026-04-02T05:21:28Z",
|
|
454
543
|
"modified_on": "2026-04-02T05:21:33Z"
|
|
455
544
|
},
|
|
@@ -504,6 +593,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
504
593
|
},
|
|
505
594
|
"billing_period_start_time": "2026-04-02T04:25:13Z",
|
|
506
595
|
"billing_period_end_time": "2026-05-02T04:25:13Z",
|
|
596
|
+
"trial_start": "2026-04-02T04:25:13Z",
|
|
597
|
+
"trial_end": "2026-04-16T04:25:13Z",
|
|
507
598
|
"created_on": "2026-04-02T04:25:20Z",
|
|
508
599
|
"modified_on": "2026-04-02T05:02:47Z"
|
|
509
600
|
},
|
|
@@ -541,6 +632,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
541
632
|
"end_date": null,
|
|
542
633
|
"billing_period_start_time": "2026-02-26T05:25:11Z",
|
|
543
634
|
"billing_period_end_time": "2026-03-26T05:25:11Z",
|
|
635
|
+
"trial_start": "2026-02-26T05:25:11Z",
|
|
636
|
+
"trial_end": "2026-03-12T05:25:11Z",
|
|
544
637
|
"customer": {
|
|
545
638
|
"id": "798e663f-2fe9-43d7-879f-2549263e20d1",
|
|
546
639
|
"name": "Geo",
|
|
@@ -574,6 +667,8 @@ The request body is a JSON object with the following top-level fields:
|
|
|
574
667
|
"end_date": null,
|
|
575
668
|
"billing_period_start_time": "2026-02-26T05:25:11Z",
|
|
576
669
|
"billing_period_end_time": "2026-03-26T05:25:11Z",
|
|
670
|
+
"trial_start": "2026-02-26T05:25:11Z",
|
|
671
|
+
"trial_end": "2026-03-12T05:25:11Z",
|
|
577
672
|
"customer": {
|
|
578
673
|
"id": "798e663f-2fe9-43d7-879f-2549263e20d1",
|
|
579
674
|
"name": "Geo",
|
|
@@ -590,6 +685,60 @@ The request body is a JSON object with the following top-level fields:
|
|
|
590
685
|
}
|
|
591
686
|
```
|
|
592
687
|
|
|
688
|
+
```json
|
|
689
|
+
{
|
|
690
|
+
"id": "7c6d5e4f-3b2a-4190-8e7d-6c5b4a3f2e1d",
|
|
691
|
+
"type": "subscription.trial_will_end",
|
|
692
|
+
"created_at": "2026-08-08T05:25:34Z",
|
|
693
|
+
"data": {
|
|
694
|
+
"object": {
|
|
695
|
+
"id": "a22f1b2a-b922-4a28-9b0e-75e826988b4b",
|
|
696
|
+
"object": "subscription",
|
|
697
|
+
"status": "trialing",
|
|
698
|
+
"plan": {
|
|
699
|
+
"name": "default pd",
|
|
700
|
+
"version": 1,
|
|
701
|
+
"identifier": "default-pd"
|
|
702
|
+
},
|
|
703
|
+
"product": {
|
|
704
|
+
"id": "b4ea7e75-5dbe-4b3b-96e0-9a31dfe5a600",
|
|
705
|
+
"name": "Migrate PD"
|
|
706
|
+
},
|
|
707
|
+
"amount": "21.24",
|
|
708
|
+
"amount_units": 2100,
|
|
709
|
+
"currency": "USD",
|
|
710
|
+
"recurrence": "1 month",
|
|
711
|
+
"start_date": "2026-08-01",
|
|
712
|
+
"end_date": null,
|
|
713
|
+
"billing_period_start_time": "2026-08-01T05:25:33Z",
|
|
714
|
+
"billing_period_end_time": "2026-08-31T05:25:33Z",
|
|
715
|
+
"trial_start": "2026-08-01T05:25:33Z",
|
|
716
|
+
"trial_end": "2026-08-11T05:25:33Z",
|
|
717
|
+
"customer": {
|
|
718
|
+
"id": "1bb69d0f-39f8-4db8-aace-e003d6e5f3ed",
|
|
719
|
+
"name": "Geo Jacob",
|
|
720
|
+
"email": "geo@example.com",
|
|
721
|
+
"customer_id": "1",
|
|
722
|
+
"billing_address": {
|
|
723
|
+
"city": "Bangalore",
|
|
724
|
+
"line1": null,
|
|
725
|
+
"line2": null,
|
|
726
|
+
"state": "Karnataka",
|
|
727
|
+
"country": "IN",
|
|
728
|
+
"postal_code": "560001"
|
|
729
|
+
}
|
|
730
|
+
},
|
|
731
|
+
"features": null,
|
|
732
|
+
"organization": "2a3664c0-cbd2-4f1c-a98f-1b4f65e3256c",
|
|
733
|
+
"created_on": "2026-08-01T05:25:34Z",
|
|
734
|
+
"modified_on": "2026-08-01T05:25:34Z"
|
|
735
|
+
}
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
`data.object` uses the same subscription payload shape as `subscription.created`/`subscription.updated`; the trial's remaining time is in `trial_end`. Kelviq sends this once, a few days before `trial_end`, mirroring Stripe's own `customer.subscription.trial_will_end` timing — it's skipped if the subscription has already converted to `active` or has no trial days left by the time Stripe's notice arrives.
|
|
741
|
+
|
|
593
742
|
```json
|
|
594
743
|
{
|
|
595
744
|
"id": "575a1aa4-3414-4e08-b4ad-6bfd3e96322d",
|
|
@@ -649,6 +798,10 @@ The request body is a JSON object with the following top-level fields:
|
|
|
649
798
|
"amount_total_units": 4000,
|
|
650
799
|
"currency": "USD",
|
|
651
800
|
"due_date": null,
|
|
801
|
+
"attempt_count": 0,
|
|
802
|
+
"next_payment_attempt": null,
|
|
803
|
+
"failure_details": null,
|
|
804
|
+
"payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
|
|
652
805
|
"order_id": null,
|
|
653
806
|
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
654
807
|
"customer": {
|
|
@@ -693,6 +846,10 @@ The request body is a JSON object with the following top-level fields:
|
|
|
693
846
|
"amount_total_units": 4000,
|
|
694
847
|
"currency": "USD",
|
|
695
848
|
"due_date": null,
|
|
849
|
+
"attempt_count": 1,
|
|
850
|
+
"next_payment_attempt": null,
|
|
851
|
+
"failure_details": null,
|
|
852
|
+
"payment_link": null,
|
|
696
853
|
"order_id": null,
|
|
697
854
|
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
698
855
|
"customer": {
|
|
@@ -726,6 +883,60 @@ The request body is a JSON object with the following top-level fields:
|
|
|
726
883
|
}
|
|
727
884
|
```
|
|
728
885
|
|
|
886
|
+
```json
|
|
887
|
+
{
|
|
888
|
+
"id": "1b8b128e-31c8-48b2-9d0b-f477ce543d58",
|
|
889
|
+
"type": "invoice.payment_failed",
|
|
890
|
+
"created_at": "2026-08-01T10:14:22Z",
|
|
891
|
+
"data": {
|
|
892
|
+
"object": {
|
|
893
|
+
"id": "INV-20260801101420-Q7M2P",
|
|
894
|
+
"object": "invoice",
|
|
895
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
896
|
+
"status": "PAYMENT_FAILED",
|
|
897
|
+
"customer_id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
898
|
+
"customer": {
|
|
899
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
900
|
+
"name": "Geo Jacob",
|
|
901
|
+
"email": "geojacob@example.com",
|
|
902
|
+
"customer_id": "geo-jacob",
|
|
903
|
+
"billing_address": {
|
|
904
|
+
"line1": null,
|
|
905
|
+
"line2": null,
|
|
906
|
+
"city": null,
|
|
907
|
+
"state": null,
|
|
908
|
+
"postal_code": "680121",
|
|
909
|
+
"country": "IN"
|
|
910
|
+
}
|
|
911
|
+
},
|
|
912
|
+
"product": {
|
|
913
|
+
"id": "df398021-477b-4e67-972d-c763a2f2ba7b",
|
|
914
|
+
"name": "ParityDeals"
|
|
915
|
+
},
|
|
916
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
917
|
+
"order_id": null,
|
|
918
|
+
"payment_link": "https://portal.kelviq.com/acme-inc/pay/aW5fMVJwb1pvU0JzdEN6eW9jUzdpUG1pdGgz",
|
|
919
|
+
"amount_total": "40",
|
|
920
|
+
"amount_total_units": 4000,
|
|
921
|
+
"currency": "USD",
|
|
922
|
+
"paid_at": null,
|
|
923
|
+
"due_date": "2026-08-01T10:14:22Z",
|
|
924
|
+
"attempt_count": 1,
|
|
925
|
+
"next_payment_attempt": "2026-08-04T10:14:22Z",
|
|
926
|
+
"failure_details": {
|
|
927
|
+
"code": "card_declined",
|
|
928
|
+
"message": "Your card was declined.",
|
|
929
|
+
"payment_method_type": "card"
|
|
930
|
+
},
|
|
931
|
+
"created_on": "2026-08-01T10:14:20Z",
|
|
932
|
+
"modified_on": "2026-08-01T10:14:22Z"
|
|
933
|
+
}
|
|
934
|
+
}
|
|
935
|
+
}
|
|
936
|
+
```
|
|
937
|
+
|
|
938
|
+
`attempt_count`, `next_payment_attempt`, and `payment_link` are also included on `invoice.created` and `invoice.paid` payloads. `failure_details` (with `code`, `message`, and `payment_method_type`) describes the most recent failed attempt and is `null` once the invoice moves past that attempt (e.g. a later `invoice.paid` for the same invoice). `payment_link` is `null` whenever the invoice isn't currently payable (e.g. already paid).
|
|
939
|
+
|
|
729
940
|
```json
|
|
730
941
|
{
|
|
731
942
|
"id": "6e76547b-9b6b-4504-af36-c8f646fa91fe",
|
|
@@ -741,6 +952,21 @@ The request body is a JSON object with the following top-level fields:
|
|
|
741
952
|
"currency": "USD",
|
|
742
953
|
"reason": "REQUESTED_BY_CUSTOMER",
|
|
743
954
|
"order_id": "ORD-20260402042513-8M80C",
|
|
955
|
+
"customer": {
|
|
956
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
957
|
+
"name": "Geo Jacob",
|
|
958
|
+
"email": "geojacob@example.com",
|
|
959
|
+
"customer_id": "geo-jacob",
|
|
960
|
+
"billing_address": {
|
|
961
|
+
"line1": null,
|
|
962
|
+
"line2": null,
|
|
963
|
+
"city": null,
|
|
964
|
+
"state": null,
|
|
965
|
+
"postal_code": "680121",
|
|
966
|
+
"country": "IN"
|
|
967
|
+
}
|
|
968
|
+
},
|
|
969
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
744
970
|
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
745
971
|
"created_on": "2026-04-02T05:41:21Z",
|
|
746
972
|
"modified_on": "2026-04-02T05:41:21Z"
|
|
@@ -764,12 +990,147 @@ The request body is a JSON object with the following top-level fields:
|
|
|
764
990
|
"currency": "USD",
|
|
765
991
|
"reason": "REQUESTED_BY_CUSTOMER",
|
|
766
992
|
"order_id": "ORD-20260402042513-8M80C",
|
|
993
|
+
"customer": {
|
|
994
|
+
"id": "c479275c-6987-4e0b-9aca-46e6e83226aa",
|
|
995
|
+
"name": "Geo Jacob",
|
|
996
|
+
"email": "geojacob@example.com",
|
|
997
|
+
"customer_id": "geo-jacob",
|
|
998
|
+
"billing_address": {
|
|
999
|
+
"line1": null,
|
|
1000
|
+
"line2": null,
|
|
1001
|
+
"city": null,
|
|
1002
|
+
"state": null,
|
|
1003
|
+
"postal_code": "680121",
|
|
1004
|
+
"country": "IN"
|
|
1005
|
+
}
|
|
1006
|
+
},
|
|
1007
|
+
"subscription_id": "a2951973-aca5-408d-bd9c-1d86827ed463",
|
|
767
1008
|
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
768
1009
|
"created_on": "2026-04-02T05:41:21Z",
|
|
769
1010
|
"modified_on": "2026-04-02T05:41:30Z"
|
|
770
|
-
}
|
|
771
|
-
|
|
772
|
-
|
|
1011
|
+
}
|
|
1012
|
+
}
|
|
1013
|
+
}
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
```json
|
|
1017
|
+
{
|
|
1018
|
+
"id": "7f9c9a3e-2b41-4b7a-9d2e-5c8f1a6b3d4e",
|
|
1019
|
+
"type": "payment_method.created",
|
|
1020
|
+
"created_at": "2026-04-02T06:12:04Z",
|
|
1021
|
+
"data": {
|
|
1022
|
+
"object": {
|
|
1023
|
+
"id": 482,
|
|
1024
|
+
"object": "payment_method",
|
|
1025
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1026
|
+
"customer_id": "geo-jacob",
|
|
1027
|
+
"customer": {
|
|
1028
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1029
|
+
"name": "Geo Jacob",
|
|
1030
|
+
"email": "geojacob@example.com",
|
|
1031
|
+
"customer_id": "geo-jacob",
|
|
1032
|
+
"billing_address": {
|
|
1033
|
+
"line1": null,
|
|
1034
|
+
"line2": null,
|
|
1035
|
+
"city": null,
|
|
1036
|
+
"state": null,
|
|
1037
|
+
"postal_code": "680121",
|
|
1038
|
+
"country": "IN"
|
|
1039
|
+
}
|
|
1040
|
+
},
|
|
1041
|
+
"method_type": "card",
|
|
1042
|
+
"method_data": {
|
|
1043
|
+
"brand": "visa",
|
|
1044
|
+
"last4": "4242",
|
|
1045
|
+
"exp_month": 12,
|
|
1046
|
+
"exp_year": 2029,
|
|
1047
|
+
"funding": "credit",
|
|
1048
|
+
"country": "US"
|
|
1049
|
+
},
|
|
1050
|
+
"is_default": true,
|
|
1051
|
+
"status": "succeeded"
|
|
1052
|
+
}
|
|
1053
|
+
}
|
|
1054
|
+
}
|
|
1055
|
+
```
|
|
1056
|
+
|
|
1057
|
+
```json
|
|
1058
|
+
{
|
|
1059
|
+
"id": "b1d4e5f6-3c72-4a9b-8e1d-6f2a9c4b7e8d",
|
|
1060
|
+
"type": "payment_method.updated",
|
|
1061
|
+
"created_at": "2026-04-02T06:15:47Z",
|
|
1062
|
+
"data": {
|
|
1063
|
+
"object": {
|
|
1064
|
+
"id": 482,
|
|
1065
|
+
"object": "payment_method",
|
|
1066
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1067
|
+
"customer_id": "geo-jacob",
|
|
1068
|
+
"customer": {
|
|
1069
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1070
|
+
"name": "Geo Jacob",
|
|
1071
|
+
"email": "geojacob@example.com",
|
|
1072
|
+
"customer_id": "geo-jacob",
|
|
1073
|
+
"billing_address": {
|
|
1074
|
+
"line1": null,
|
|
1075
|
+
"line2": null,
|
|
1076
|
+
"city": null,
|
|
1077
|
+
"state": null,
|
|
1078
|
+
"postal_code": "680121",
|
|
1079
|
+
"country": "IN"
|
|
1080
|
+
}
|
|
1081
|
+
},
|
|
1082
|
+
"method_type": "card",
|
|
1083
|
+
"method_data": {
|
|
1084
|
+
"brand": "visa",
|
|
1085
|
+
"last4": "4242",
|
|
1086
|
+
"exp_month": 12,
|
|
1087
|
+
"exp_year": 2029,
|
|
1088
|
+
"funding": "credit",
|
|
1089
|
+
"country": "US"
|
|
1090
|
+
},
|
|
1091
|
+
"is_default": true,
|
|
1092
|
+
"status": "succeeded"
|
|
1093
|
+
}
|
|
1094
|
+
}
|
|
1095
|
+
}
|
|
1096
|
+
```
|
|
1097
|
+
|
|
1098
|
+
```json
|
|
1099
|
+
{
|
|
1100
|
+
"id": "e3a2b1c0-9d8e-47f6-b5a4-1c2d3e4f5a6b",
|
|
1101
|
+
"type": "payment_method.deleted",
|
|
1102
|
+
"created_at": "2026-04-02T06:20:12Z",
|
|
1103
|
+
"data": {
|
|
1104
|
+
"object": {
|
|
1105
|
+
"id": 482,
|
|
1106
|
+
"object": "payment_method",
|
|
1107
|
+
"organization": "9b759915-5387-4e61-90e9-2162318e8d17",
|
|
1108
|
+
"customer_id": "geo-jacob",
|
|
1109
|
+
"customer": {
|
|
1110
|
+
"id": "936cf361-3a4b-454c-a464-41ccc7600c2d",
|
|
1111
|
+
"name": "Geo Jacob",
|
|
1112
|
+
"email": "geojacob@example.com",
|
|
1113
|
+
"customer_id": "geo-jacob",
|
|
1114
|
+
"billing_address": {
|
|
1115
|
+
"line1": null,
|
|
1116
|
+
"line2": null,
|
|
1117
|
+
"city": null,
|
|
1118
|
+
"state": null,
|
|
1119
|
+
"postal_code": "680121",
|
|
1120
|
+
"country": "IN"
|
|
1121
|
+
}
|
|
1122
|
+
},
|
|
1123
|
+
"method_type": "card",
|
|
1124
|
+
"method_data": {
|
|
1125
|
+
"brand": "visa",
|
|
1126
|
+
"last4": "4242",
|
|
1127
|
+
"exp_month": 12,
|
|
1128
|
+
"exp_year": 2029,
|
|
1129
|
+
"funding": "credit",
|
|
1130
|
+
"country": "US"
|
|
1131
|
+
},
|
|
1132
|
+
"is_default": false,
|
|
1133
|
+
"status": "succeeded"
|
|
773
1134
|
}
|
|
774
1135
|
}
|
|
775
1136
|
}
|
|
@@ -1031,7 +1392,7 @@ func main() {
|
|
|
1031
1392
|
## Best Practices
|
|
1032
1393
|
|
|
1033
1394
|
- **Return `2xx` fast.** Acknowledge the webhook immediately and process it asynchronously. Long-running handlers increase the risk of timeouts and duplicate retries.
|
|
1034
|
-
- **Make handlers idempotent.** The same event may be delivered more than once. Use `
|
|
1395
|
+
- **Make handlers idempotent.** The same event may be delivered more than once. Use the top-level event `id` or the `webhook-id` header as the deduplication key.
|
|
1035
1396
|
- **Validate the timestamp.** Reject requests where `webhook-timestamp` is more than 5 minutes from your server's clock to prevent replay attacks.
|
|
1036
1397
|
- **Use `hmac.compare_digest` / `hmac.Equal` / `crypto.timingSafeEqual`.** Constant-time comparison prevents timing side-channel attacks.
|
|
1037
1398
|
- **Store the raw body before parsing.** Signature verification operates on the raw bytes, not the deserialized object.
|