DR-370 update payments docs referencing Ddevvit singleton (#67)

## 💸 TL;DR
<!-- What's the three sentence summary of purpose of the PR -->
This updates payments docs referencing Devvit Singleton

<!-- Add additional details required for the PR: breaking changes,
screenshots, external dependency changes -->
This PR used cursor pretty heavily I read through the changes but
@RarerAirError just a heads up.

## 🧪 Testing Steps / Validation
<!-- add details on how this PR has been tested, include reproductions
and screenshots where applicable -->

## ✅ Checks
<!-- Make sure your pr passes the CI checks and do check the following
fields as needed - -->
- [ ] CI tests (if present) are passing
- [ ] Adheres to code style for repo
- [ ] Contributor License Agreement (CLA) completed if not a Reddit
employee

Author: vdikransamarjian

docs/earn-money/payments/payments_add.mdx

@@ -255,31 +255,13 @@ If you don’t provide an image, the default Reddit product image is used.
 
 ### Purchase buttons (required)
 
-#### Blocks
+#### Devvit Web
 
-The `ProductButton` is a Devvit blocks component designed to render a product with a purchase button. It can be customized to match your app's look and feel.
+In Devvit Web, use your own UI (e.g. a button or product card) and call `purchase(sku)` from `@devvit/web/client` when the user chooses a product. Follow the [design guidelines](#design-guidelines) (e.g. gold icon, clear labeling).
 
-**Usage:**
+#### Blocks (legacy)
 
-```tsx
-<ProductButton
-  showIcon
-  product={product}
-  onPress={(p) => payments.purchase(p.sku)}
-  appearance="tile"
-/>
-```
-
-##### `ProductButtonProps`
-
-| **Prop Name**      | **Type**                                        | **Description**                                                                      |
-| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `product`          | `Product`                                       | The product object containing details such as `sku`, `price`, and `metadata`.        |
-| `onPress`          | `(product: Product) => void`                    | Callback function triggered when the button is pressed.                              |
-| `showIcon`         | `boolean`                                       | Determines whether the product icon is displayed on the button. Defaults to `false`. |
-| `appearance`       | `'compact'` &#124; `'detailed'` &#124; `'tile'` | Defines the visual style of the button. Defaults to `compact`.                       |
-| `buttonAppearance` | `string`                                        | Optional [button appearance](../../blocks/button.mdx#appearance).                    |
-| `textColor`        | `string`                                        | Optional [text color](../../blocks/text.mdx#color).                                  |
+If your app still uses Devvit Blocks, you can use the `ProductButton` component and [migrate to Devvit Web](./payments_migrate.mdx) when ready. The `ProductButton` renders a product with a purchase button; use `payments.purchase(p.sku)` in the `onPress` callback (from `@devvit/payments`).
 
 #### Webviews
 
@@ -297,36 +279,30 @@ Use a consistent and clear product component to display paid goods or services t
 
 ## Complete the payment flow
 
-Use `addPaymentHandler` to specify the function that is called during the order flow. This customizes how your app fulfills product orders and provides the ability for you to reject an order.
+Your **fulfill** endpoint (configured in `devvit.json` and implemented in the server) is called during the order flow. It customizes how your app fulfills product orders and lets you reject an order.
 
-Errors thrown within the payment handler automatically reject the order. To provide a custom error message to the frontend of your application, you can return `{success: false, reason: <string>}` with a reason for the order rejection.
+Return `{ success: true }` to accept the order, or `{ success: false, reason: "<string>" }` to reject it and send a message to the client. Throwing an error in the handler also rejects the order.
 
-This example shows how to issue an "extra life" to a user when they purchase the "extra_life" product.
+This example shows how to grant an "extra life" in your fulfill endpoint when the user purchases the "god_mode" product (using Redis from `@devvit/web/server`):
 
-```ts
-import { type Context } from "@devvit/public-api";
-import { addPaymentHandler } from "@devvit/payments";
-import { Devvit, useState } from "@devvit/public-api";
-
-Devvit.configure({
-  redis: true,
-  redditAPI: true,
-});
+```tsx title="server/index.ts"
+import type { PaymentHandlerResponse, Order } from "@devvit/web/server";
+import { redis } from "@devvit/web/server";
 
 const GOD_MODE_SKU = "god_mode";
 
-addPaymentHandler({
-  fulfillOrder: async (order, ctx) => {
-    if (!order.products.some(({ sku }) => sku === GOD_MODE_SKU)) {
-      throw new Error("Unable to fulfill order: sku not found");
-    }
-    if (order.status !== "PAID") {
-      throw new Error("Becoming a god has a cost (in Reddit Gold)");
-    }
+app.post("/internal/payments/fulfill", async (c) => {
+  const order = await c.req.json<Order>();
+  if (!order.products.some((p) => p.sku === GOD_MODE_SKU)) {
+    return c.json<PaymentHandlerResponse>({ success: false, reason: "Unable to fulfill order: sku not found" });
+  }
+  if (order.status !== "PAID") {
+    return c.json<PaymentHandlerResponse>({ success: false, reason: "Becoming a god has a cost (in Reddit Gold)" });
+  }
 
-    const redisKey = godModeRedisKey(ctx.postId, ctx.userId);
-    await ctx.redis.set(redisKey, "true");
-  },
+  const redisKey = `post:${order.postId}:user:${order.userId}:god_mode`;
+  await redis.set(redisKey, "true");
+  return c.json<PaymentHandlerResponse>({ success: true });
 });
 ```
 
@@ -336,61 +312,44 @@ The frontend and backend of your app coordinate order processing.
 
 ![Order workflow diagram](../../assets/payments_order_flow_diagram.png)
 
-To launch the payment flow, create a hook with `usePayments()` followed by `hook.purchase()` to initiate the purchase from the frontend.
+To launch the payment flow, call `purchase(sku)` from `@devvit/web/client`. That triggers the native payment flow on all platforms (web, iOS, Android); Reddit then calls your server's **fulfill** endpoint. Your app can acknowledge or reject the order (for example, reject once a limited product is sold out).
 
-This triggers a native payment flow on all platforms (web, iOS, Android) that works with the Reddit backend to process the order. The `fulfillOrder()` hook calls your app during this process.
+### Get your product details
 
-Your app can acknowledge or reject the order. For example, for goods with limited quantities, your app may reject an order once the product is sold out.
+**Server:** Use `payments.getProducts()` in your server (see [Server: Fetch products](#server-fetch-products)) and expose products via your own `/api/products` (or similar) endpoint if the client needs them.
 
-### Get your product details
+**Client:** Fetch product metadata from your API and use it to display products and call `purchase(sku)`:
 
-Use the `useProducts` hook or `getProducts` function to fetch details about products.
-
-```tsx
-import { useProducts } from "@devvit/payments";
-
-export function ProductsList(context: Devvit.Context): JSX.Element {
-  // Only query for products with the metadata "category" of value "powerup".
-  // The metadata field can be empty - if it is, useProducts will not filter on metadata.
-  const { products } = useProducts(context, {
-    metadata: {
-      category: "powerup",
-    },
-  });
-
-  return (
-    <vstack>
-      {products.map((product) => (
-        <hstack>
-          <text>{product.name}</text>
-          <text>{product.price}</text>
-        </hstack>
-      ))}
-    </vstack>
-  );
-}
-```
+```tsx title="client/index.ts"
+import { purchase, OrderResultStatus } from "@devvit/web/client";
 
-You can also fetch all products using custom-defined metadata or by an array of skus. Only one is required; if you provide both then they will be AND’d.
+// Fetch products from your server endpoint
+const products = await fetch("/api/products").then((r) => r.json());
 
-```tsx
-import { getProducts } from '@devvit/payments';
-const products = await getProducts({,
-});
+// Render your UI; when user chooses a product:
+async function handleBuy(sku: string) {
+  const result = await purchase(sku);
+  if (result.status === OrderResultStatus.STATUS_SUCCESS) {
+    // show success
+  } else {
+    // show error or retry (result.errorMessage may be set)
+  }
+}
 ```
 
 ### Initiate orders
 
-Provide the product sku to trigger a purchase. This automatically populates the most recently-approved product metadata for that product id.
-
-**Example**
-
-```tsx
-import { usePayments } from '@devvit/payments';
+Provide the product SKU to trigger a purchase. Use `purchase(sku)` from `@devvit/web/client`; the result indicates success or failure.
 
-// handles purchase results
-const payments = usePayments((result: OnPurchaseResult) => { console.log('Tried to buy:', result.sku, '; result:', result.status); });
+```tsx title="client/index.ts"
+import { purchase, OrderResultStatus } from "@devvit/web/client";
 
-// for each sku in products:
-<button onPress{payments.purchase(sku)}>Buy a {sku}</button>
+export async function buy(sku: string) {
+  const result = await purchase(sku);
+  if (result.status === OrderResultStatus.STATUS_SUCCESS) {
+    // show success
+  } else {
+    // show error or retry (result.errorMessage may be set)
+  }
+}
 ```

docs/earn-money/payments/payments_manage.md

@@ -4,30 +4,23 @@ Once your app and products have been approved, you’re ready to use Reddit’s
 
 ## Check orders
 
-Reddit keeps track of historical purchases and lets you query user purchases.
+Reddit keeps track of historical purchases and lets you query orders.
 
-Orders are returned in reverse chronological order and can be filtered based on user, product, success state, or other attributes.
+In Devvit Web, use **server-side** `payments.getOrders()` from `@devvit/web/server`. Orders are returned in reverse chronological order and can be filtered by user, product, success state, or other attributes. Expose the data to your client via your own API (e.g. `/api/orders`) if the client needs it.
 
-**Example**
+**Example (server):** expose orders for the current user so the client can show "Purchased!" or a purchase button.
 
-```tsx
-import { useOrders, OrderStatus } from '@devvit/payments';
+```tsx title="server/index.ts"
+import { payments } from "@devvit/web/server";
 
-export function CosmicSwordShop(context: Devvit.Context): JSX.Element {
-  const { orders } = useOrders(context, {
-    sku: 'cosmic_sword',
-  });
-
-  // if the user hasn’t already bought the cosmic sword
-  // then show them the purchase button
-  if (orders.length > 0) {
-    return <text>Purchased!</text>;
-  } else {
-    return <button onPress={/* Trigger purchase */}>Buy Cosmic Sword</button>;
-  }
-}
+app.get("/api/orders", async (c) => {
+  const orders = await payments.getOrders({ sku: "cosmic_sword" });
+  return c.json(orders);
+});
 ```
 
+**Client:** call your `/api/orders` endpoint; if the user has already bought the product, show "Purchased!"; otherwise show a button that calls `purchase("cosmic_sword")` from `@devvit/web/client`.
+
 ## Update products
 
 Once your app is in production, existing installations will need to be manually updated via the admin tool if you release a new version. Contact the Developer Platform team if you need to update your app installation versions.
@@ -38,25 +31,23 @@ Automatic updates will be supported in a future release.
 
 Reddit may reverse transactions under certain circumstances, such as card disputes, policy violations, or technical issues. If there’s a problem with a digital good, a user can submit a request for a refund via [Reddit Help](https://support.reddithelp.com/hc/en-us/requests/new?ticket_form_id=29770197409428).
 
-When a transaction is reversed for any reason, you may optionally revoke product functionality from the user by adding a `refundOrder` handler.
-
-**Example**
-
-```tsx
-addPaymentHandler({
-  fulfillOrder: async (order: Order, ctx: Context) => {
-    // Snip order fulfillment
-  },
-  refundOrder: async (order: Order, ctx: Context) => {
-    // check if the order contains an extra life
-    if (order.products.some(({ sku }) => sku === GOD_MODE_SKU)) {
-      // redis key for storing number of lives user has left
-      const livesKey = `${ctx.userId}:lives`;
-
-      // if so, decrement the number of lives
-      await ctx.redis.incrBy(livesKey, -1);
-    }
-  },
+When a transaction is reversed for any reason, you may optionally revoke product functionality from the user by implementing the **refund** endpoint (configured in `devvit.json` under `payments.endpoints.refundOrder`).
+
+**Example (Devvit Web):** in your server’s refund endpoint, revoke the entitlement (e.g. decrement lives in Redis).
+
+```tsx title="server/index.ts"
+import type { PaymentHandlerResponse, Order } from "@devvit/web/server";
+import { redis } from "@devvit/web/server";
+
+const GOD_MODE_SKU = "god_mode";
+
+app.post("/internal/payments/refund", async (c) => {
+  const order = await c.req.json<Order>();
+  if (order.products.some((p) => p.sku === GOD_MODE_SKU)) {
+    const livesKey = `${order.userId}:lives`;
+    await redis.incrBy(livesKey, -1);
+  }
+  return c.json<PaymentHandlerResponse>({ success: true });
 });
 ```
 

docs/earn-money/payments/support_this_app.md

@@ -19,45 +19,50 @@ devvit products add support-app
 
 ### Add a payment handler
 
-The [payment handler](./payments_add.mdx#complete-the-payment-flow) is where you award the promised incentive to your supporters. For example, this is how you can award custom user flair:
+In Devvit Web, the [payment handler](./payments_add.mdx#complete-the-payment-flow) is your server’s **fulfill** endpoint. That’s where you award the promised incentive (e.g. custom user flair). Implement it in your server and reference it in `devvit.json` under `payments.endpoints.fulfillOrder`.
 
-```tsx
-addPaymentHandler({
-  fulfillOrder: async (order, context) => {
-    const username = await context.reddit.getCurrentUsername();
-    if (!username) {
-      throw new Error("User not found");
-    }
-
-    const subredditName = await context.reddit.getCurrentSubredditName();
-
-    await context.reddit.setUserFlair({
-      text: "Super Duper User",
-      subredditName,
-      username,
-      backgroundColor: "#ffbea6",
-      textColor: "dark",
-    });
-  },
+Example: award custom user flair when a user completes a support purchase:
+
+```tsx title="server/index.ts"
+import type { PaymentHandlerResponse, Order } from "@devvit/web/server";
+import { reddit } from "@devvit/web/server";
+
+app.post("/internal/payments/fulfill", async (c) => {
+  const order = await c.req.json<Order>();
+  const username = order.userId; // or the username field on the order
+  if (!username) {
+    return c.json<PaymentHandlerResponse>({ success: false, reason: "User not found" });
+  }
+
+  const subredditName = order.subredditName ?? order.subredditId;
+
+  await reddit.setUserFlair({
+    text: "Super Duper User",
+    subredditName,
+    username,
+    backgroundColor: "#ffbea6",
+    textColor: "dark",
+  });
+
+  return c.json<PaymentHandlerResponse>({ success: true });
 });
 ```
 
 ### Initiate purchases
 
-Next you need to provide a way for users to support your app:
+Provide a way for users to support your app from your client:
 
-- If you use Devvit blocks, you can use the ProductButton helper to render a purchase button.
-- If you use webviews, make sure that your design follows the [design guidelines](./payments_add.mdx#design-guidelines) to [initiate purchases](./payments_add.mdx#initiate-orders).
+- **Devvit Web:** Add a button or link that calls `purchase("support-app")` from `@devvit/web/client`. Handle the result (e.g. show a toast on success). Optionally fetch product info from your `/api/products` endpoint to display the support option.
+- Follow the [design guidelines](./payments_add.mdx#design-guidelines) when [initiating purchases](./payments_add.mdx#initiate-orders).
 
 ![Support App Example](../../assets/support_this_app.png)
 
-Here's how you create a ProductButton in blocks:
+Example client code:
 
-```tsx
-import { usePayments, useProducts } from '@devvit/payments';
-import { ProductButton } from '@devvit/payments/helpers/ProductButton';
-import { Devvit } from '@devvit/public-api';
+```tsx title="client/index.ts"
+import { purchase, OrderResultStatus } from "@devvit/web/client";
 
+<<<<<<< HEAD
 // addCustomPostType() is deprecated and will be unsupported. It will not work after June 30. View the announcement below this example.
 Devvit.addCustomPostType({
   render: (context) => {
@@ -82,6 +87,16 @@ Devvit.addCustomPostType({
      />
    );
 })
+=======
+async function handleSupportApp() {
+  const result = await purchase("support-app");
+  if (result.status === OrderResultStatus.STATUS_SUCCESS) {
+    // show success, e.g. toast: "Thanks for your support!"
+  } else {
+    // show error or retry (result.errorMessage may be set)
+  }
+}
+>>>>>>> 64da331 (DR-370 update payments docs referencing Ddevvit singleton)
 ```
 [View `addCustomPostType` deprecation announcement.](https://www.reddit.com/r/Devvit/comments/1r3xcm2/devvit_web_and_the_future_of_devvit/)