@eventcatalog/create-eventcatalog 4.3.12-beta.1 → 4.3.13

package/templates/default/domains/Payments/systems/payment-processing-system/services/PaymentWorker/events/RefundRequested/examples/index.mdx

@@ -0,0 +1,194 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Request a full refund for a cancelled order
+
+The customer cancels their T-shirt and cap order before it is dispatched. The PaymentWorker publishes `RefundRequested` so Stripe returns the full charge.
+
+### Payload details
+
+- `refundId` identifies this refund; `paymentId` is the original charge being refunded.
+- `orderId` is included so the refund can be traced back to the cancelled order.
+- `amount` matches the original charge, in pence.
+- `reason` is free text recorded for support and reporting.
+
+The refund is **4,298 pence (£42.98)**, the full amount of the original payment.
+
+### Using this example
+
+Consumers should refund `amount` against `paymentId` and reply with a `RefundProcessed` event that carries the same `refundId`.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RefundRequested schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-refund-requested.ts
+import { EventsClient } from '@acme/events';
+import type { RefundRequested } from './schemas/refund-requested';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RefundRequested = {
+  refundId: 'b5e477d7-f910-43f5-a371-e9f3f53cfaa2',
+  paymentId: '586e57ab-77a9-406a-945d-4619c76a582e',
+  orderId: '971b5a4b-6885-405c-899b-5e0f428016c1',
+  amount: 4298,
+  currency: 'GBP',
+  reason: 'Order cancelled by customer before dispatch',
+  requestedAt: '2026-09-11T14:05:10Z',
+};
+
+await client.publish('RefundRequested', event);
+```
+
+```python publish_refund_requested.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "refundId": "b5e477d7-f910-43f5-a371-e9f3f53cfaa2",
+    "paymentId": "586e57ab-77a9-406a-945d-4619c76a582e",
+    "orderId": "971b5a4b-6885-405c-899b-5e0f428016c1",
+    "amount": 4298,
+    "currency": "GBP",
+    "reason": "Order cancelled by customer before dispatch",
+    "requestedAt": "2026-09-11T14:05:10Z",
+}
+
+client.publish("RefundRequested", event)
+```
+
+```java PublishRefundRequested.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRefundRequested {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "refundId", "b5e477d7-f910-43f5-a371-e9f3f53cfaa2",
+      "paymentId", "586e57ab-77a9-406a-945d-4619c76a582e",
+      "orderId", "971b5a4b-6885-405c-899b-5e0f428016c1",
+      "amount", 4298,
+      "currency", "GBP",
+      "reason", "Order cancelled by customer before dispatch",
+      "requestedAt", "2026-09-11T14:05:10Z"
+    );
+
+    client.publish("RefundRequested", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Request a partial refund for a returned item
+
+The guest shopper returns one of the three hoodies. The PaymentWorker publishes `RefundRequested` for that item only, using just the required fields.
+
+### Payload details
+
+- `paymentId` is the original €164.97 charge; only part of it is refunded.
+- `amount` is one hoodie at €54.99, in cents.
+- `orderId` and `reason` are optional and omitted here.
+
+The refund is **5,499 cents (€54.99)**, leaving 10,998 cents (€109.98) charged.
+
+### Using this example
+
+Use this payload to check that consumers support partial refunds, where `amount` is less than the original charge.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the RefundRequested schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-refund-requested.ts
+import { EventsClient } from '@acme/events';
+import type { RefundRequested } from './schemas/refund-requested';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: RefundRequested = {
+  refundId: 'f57e3268-60d1-4b1d-96e9-c27d47992d47',
+  paymentId: '41651c3f-fa8e-40fc-a217-a83929d15081',
+  amount: 5499,
+  currency: 'EUR',
+  requestedAt: '2026-09-21T09:40:00Z',
+};
+
+await client.publish('RefundRequested', event);
+```
+
+```python publish_refund_requested.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "refundId": "f57e3268-60d1-4b1d-96e9-c27d47992d47",
+    "paymentId": "41651c3f-fa8e-40fc-a217-a83929d15081",
+    "amount": 5499,
+    "currency": "EUR",
+    "requestedAt": "2026-09-21T09:40:00Z",
+}
+
+client.publish("RefundRequested", event)
+```
+
+```java PublishRefundRequested.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishRefundRequested {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "refundId", "f57e3268-60d1-4b1d-96e9-c27d47992d47",
+      "paymentId", "41651c3f-fa8e-40fc-a217-a83929d15081",
+      "amount", 5499,
+      "currency", "EUR",
+      "requestedAt", "2026-09-21T09:40:00Z"
+    );
+
+    client.publish("RefundRequested", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentFailed/examples/index.mdx

@@ -0,0 +1,265 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Report a declined card
+
+The customer's bank declines the card for a hoodie order. The StripeWebhookEndpoint publishes `PaymentFailed` and the PaymentWorker records the payment as failed, which leads to the order being cancelled.
+
+### Payload details
+
+- `reason` is `CARD_DECLINED`: the issuing bank refused the charge.
+- `paymentId` and `orderId` identify the failed payment and its order.
+- `failedAt` is when Stripe reported the failure.
+
+### Using this example
+
+Consumers should mark the payment as failed and start cancelling `orderId`. The customer can be asked to try another card.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the PaymentFailed schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-payment-failed.ts
+import { EventsClient } from '@acme/events';
+import type { PaymentFailed } from './schemas/payment-failed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: PaymentFailed = {
+  paymentId: '428dc169-43a6-479d-9661-5b07984cb556',
+  orderId: '2d7ef31b-211a-4dbc-898a-0b095e7b909c',
+  reason: 'CARD_DECLINED',
+  failedAt: '2026-09-16T02:47:20Z',
+};
+
+await client.publish('PaymentFailed', event);
+```
+
+```python publish_payment_failed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "paymentId": "428dc169-43a6-479d-9661-5b07984cb556",
+    "orderId": "2d7ef31b-211a-4dbc-898a-0b095e7b909c",
+    "reason": "CARD_DECLINED",
+    "failedAt": "2026-09-16T02:47:20Z",
+}
+
+client.publish("PaymentFailed", event)
+```
+
+```java PublishPaymentFailed.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishPaymentFailed {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "paymentId", "428dc169-43a6-479d-9661-5b07984cb556",
+      "orderId", "2d7ef31b-211a-4dbc-898a-0b095e7b909c",
+      "reason", "CARD_DECLINED",
+      "failedAt", "2026-09-16T02:47:20Z"
+    );
+
+    client.publish("PaymentFailed", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Report an expired card
+
+A customer pays for a cap with a saved card that has expired. Stripe rejects the charge and the StripeWebhookEndpoint publishes `PaymentFailed`.
+
+### Payload details
+
+- `reason` is `EXPIRED_CARD`: the card's expiry date has passed.
+- This is caused by the customer's card details, so retrying the same card will not help.
+
+### Using this example
+
+Use this payload to check that consumers prompt the customer to update their card rather than retrying.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the PaymentFailed schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-payment-failed.ts
+import { EventsClient } from '@acme/events';
+import type { PaymentFailed } from './schemas/payment-failed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: PaymentFailed = {
+  paymentId: 'dfdffee1-3e4d-4fa3-b86e-ebe0cd93ca60',
+  orderId: '76d60366-d78a-4e10-b1ad-832445febfa1',
+  reason: 'EXPIRED_CARD',
+  failedAt: '2026-09-17T11:20:09Z',
+};
+
+await client.publish('PaymentFailed', event);
+```
+
+```python publish_payment_failed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "paymentId": "dfdffee1-3e4d-4fa3-b86e-ebe0cd93ca60",
+    "orderId": "76d60366-d78a-4e10-b1ad-832445febfa1",
+    "reason": "EXPIRED_CARD",
+    "failedAt": "2026-09-17T11:20:09Z",
+}
+
+client.publish("PaymentFailed", event)
+```
+
+```java PublishPaymentFailed.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishPaymentFailed {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "paymentId", "dfdffee1-3e4d-4fa3-b86e-ebe0cd93ca60",
+      "orderId", "76d60366-d78a-4e10-b1ad-832445febfa1",
+      "reason", "EXPIRED_CARD",
+      "failedAt", "2026-09-17T11:20:09Z"
+    );
+
+    client.publish("PaymentFailed", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 3. Report a processing error
+
+Stripe has a temporary problem while charging a T-shirt order. The StripeWebhookEndpoint publishes `PaymentFailed` even though the card itself is fine.
+
+### Payload details
+
+- `reason` is `PROCESSING_ERROR`: the failure is on the processor side, not the customer's card.
+- This is the only reason in the schema where a retry may succeed.
+
+### Using this example
+
+Use this payload to test retry handling: consumers may retry the charge before cancelling the order.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the PaymentFailed schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-payment-failed.ts
+import { EventsClient } from '@acme/events';
+import type { PaymentFailed } from './schemas/payment-failed';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: PaymentFailed = {
+  paymentId: '0c3b8e41-5a7f-4d26-9e18-b4f2a6d09c75',
+  orderId: '99027891-075d-4561-91f8-da95f34e4a57',
+  reason: 'PROCESSING_ERROR',
+  failedAt: '2026-09-18T16:55:48Z',
+};
+
+await client.publish('PaymentFailed', event);
+```
+
+```python publish_payment_failed.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "paymentId": "0c3b8e41-5a7f-4d26-9e18-b4f2a6d09c75",
+    "orderId": "99027891-075d-4561-91f8-da95f34e4a57",
+    "reason": "PROCESSING_ERROR",
+    "failedAt": "2026-09-18T16:55:48Z",
+}
+
+client.publish("PaymentFailed", event)
+```
+
+```java PublishPaymentFailed.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishPaymentFailed {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "paymentId", "0c3b8e41-5a7f-4d26-9e18-b4f2a6d09c75",
+      "orderId", "99027891-075d-4561-91f8-da95f34e4a57",
+      "reason", "PROCESSING_ERROR",
+      "failedAt", "2026-09-18T16:55:48Z"
+    );
+
+    client.publish("PaymentFailed", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>

package/templates/default/domains/Payments/systems/stripe/services/StripeWebhookEndpoint/events/PaymentSucceeded/examples/index.mdx

@@ -0,0 +1,190 @@
+<Columns cols={2}>
+
+<Column>
+
+## 1. Confirm a card charge with a Stripe reference
+
+Stripe charges the card for the T-shirt and cap order. The StripeWebhookEndpoint publishes `PaymentSucceeded` and the PaymentWorker records the payment as succeeded.
+
+### Payload details
+
+- `paymentId` and `orderId` match the original `PaymentRequested` event.
+- `amount` and `currency` are what Stripe actually charged, in pence.
+- `processorReference` is Stripe's charge ID, kept for reconciliation and refunds.
+
+The customer was charged **4,298 pence (£42.98)**.
+
+### Using this example
+
+Consumers should check that `amount` and `currency` match the requested charge before marking the payment as succeeded.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the PaymentSucceeded schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-payment-succeeded.ts
+import { EventsClient } from '@acme/events';
+import type { PaymentSucceeded } from './schemas/payment-succeeded';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: PaymentSucceeded = {
+  paymentId: '586e57ab-77a9-406a-945d-4619c76a582e',
+  orderId: '971b5a4b-6885-405c-899b-5e0f428016c1',
+  amount: 4298,
+  currency: 'GBP',
+  processorReference: 'ch_3PqL8x2eZvKYlo2C1a9bR4tD',
+  succeededAt: '2026-09-11T08:12:52Z',
+};
+
+await client.publish('PaymentSucceeded', event);
+```
+
+```python publish_payment_succeeded.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "paymentId": "586e57ab-77a9-406a-945d-4619c76a582e",
+    "orderId": "971b5a4b-6885-405c-899b-5e0f428016c1",
+    "amount": 4298,
+    "currency": "GBP",
+    "processorReference": "ch_3PqL8x2eZvKYlo2C1a9bR4tD",
+    "succeededAt": "2026-09-11T08:12:52Z",
+}
+
+client.publish("PaymentSucceeded", event)
+```
+
+```java PublishPaymentSucceeded.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishPaymentSucceeded {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "paymentId", "586e57ab-77a9-406a-945d-4619c76a582e",
+      "orderId", "971b5a4b-6885-405c-899b-5e0f428016c1",
+      "amount", 4298,
+      "currency", "GBP",
+      "processorReference", "ch_3PqL8x2eZvKYlo2C1a9bR4tD",
+      "succeededAt", "2026-09-11T08:12:52Z"
+    );
+
+    client.publish("PaymentSucceeded", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>
+
+---
+
+<Columns cols={2}>
+
+<Column>
+
+## 2. Confirm a charge without a processor reference
+
+Stripe confirms the guest hoodie payment. The webhook arrives without a charge ID, so only the required fields are published.
+
+### Payload details
+
+- `processorReference` is optional and omitted here.
+- `amount` is three hoodies at €54.99 each, in cents.
+- `currency` is `EUR`.
+
+The customer was charged **16,497 cents (€164.97)**.
+
+### Using this example
+
+Use this payload to check that the PaymentWorker records the payment even when `processorReference` is missing.
+
+The examples use a **fictional Acme Events SDK** to publish a payload matching the PaymentSucceeded schema. The package names and publish methods are illustrative.
+
+</Column>
+
+<Column>
+
+<CodeGroup dropdown>
+
+```typescript publish-payment-succeeded.ts
+import { EventsClient } from '@acme/events';
+import type { PaymentSucceeded } from './schemas/payment-succeeded';
+
+const client = new EventsClient({
+  apiKey: process.env.ACME_API_KEY!,
+});
+
+const event: PaymentSucceeded = {
+  paymentId: '41651c3f-fa8e-40fc-a217-a83929d15081',
+  orderId: 'e39a80be-526e-4009-a22a-40c847cff088',
+  amount: 16497,
+  currency: 'EUR',
+  succeededAt: '2026-09-14T19:03:34Z',
+};
+
+await client.publish('PaymentSucceeded', event);
+```
+
+```python publish_payment_succeeded.py
+import os
+from acme_events import EventsClient
+
+client = EventsClient(api_key=os.environ["ACME_API_KEY"])
+
+event = {
+    "paymentId": "41651c3f-fa8e-40fc-a217-a83929d15081",
+    "orderId": "e39a80be-526e-4009-a22a-40c847cff088",
+    "amount": 16497,
+    "currency": "EUR",
+    "succeededAt": "2026-09-14T19:03:34Z",
+}
+
+client.publish("PaymentSucceeded", event)
+```
+
+```java PublishPaymentSucceeded.java
+import com.acme.events.EventsClient;
+import java.util.Map;
+
+public class PublishPaymentSucceeded {
+  public static void main(String[] args) {
+    var client = new EventsClient(
+      System.getenv("ACME_API_KEY")
+    );
+
+    var event = Map.of(
+      "paymentId", "41651c3f-fa8e-40fc-a217-a83929d15081",
+      "orderId", "e39a80be-526e-4009-a22a-40c847cff088",
+      "amount", 16497,
+      "currency", "EUR",
+      "succeededAt", "2026-09-14T19:03:34Z"
+    );
+
+    client.publish("PaymentSucceeded", event);
+  }
+}
+```
+
+</CodeGroup>
+
+</Column>
+
+</Columns>