Add Pay.sh pages for Accept Payments and Subscriptions

apps/docs/content/docs/en/payments/accept-payments/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Accept Payments",
-  "pages": ["payment-button", "verification-tools", "indexing"],
+  "pages": ["payment-button", "verification-tools", "indexing", "pay-sh"],
   "defaultOpen": false
 }

apps/docs/content/docs/en/payments/accept-payments/pay-sh.mdx

@@ -0,0 +1,68 @@
+---
+title: With Pay.sh
+description: Accept payments with Pay.sh.
+---
+
+You can accept payments on API requests via Pay.sh by setting up a Pay server.
+Install Pay with:
+
+```bash
+brew install pay
+```
+
+or
+
+```bash
+npm install -g @solana/pay
+```
+
+Verify the installation with:
+
+```bash
+pay --version
+```
+
+The toolchain will set up your address for you. Run the following to setup and
+topup your wallet:
+
+```bash
+pay setup
+pay topup
+```
+
+## Setting up the demo server
+
+You can start accepting payments by starting your server. You can see a demo
+server in action with:
+
+```bash
+pay --sandbox server demo
+```
+
+This does two things. It starts a live Pay server which you can query via HTTP
+request, and it generates a `pay-demo.yml` file in your current directory.
+
+All API routes are configured via the `endpoints` YAML config. In order to
+accept payments, you have to add a `metering:` attribute. The
+`/api/v1/reports/usage` route has been done as an example for you:
+
+```yaml
+endpoints:
+  - method: GET
+    path: "api/v1/reports/usage"
+    resource: "reports"
+    description: "Usage report — flat fee, no splits."
+    metering:
+      dimensions:
+        - direction: usage
+          unit: requests
+          scale: 1
+          tiers:
+            - price_usd: 0.01
+```
+
+You can learn more about how to define pricing in the
+[Pay.sh Building with Pay > Pricing docs](https://pay.sh/docs/building-with-pay/pricing)
+
+Learn more about setting up Pay.sh in production in the
+[Pay.sh Configuration docs](https://pay.sh/docs/toolchain/configuration).

apps/docs/content/docs/en/payments/agentic-payments.mdx

@@ -33,6 +33,32 @@ APIs without provider accounts or API keys. When an API returns an MPP or x402
 `402 Payment Required` challenge, `pay` asks your local wallet to approve
 signing.
 
+You can install Pay with:
+
+```bash
+brew install pay
+```
+
+or
+
+```bash
+npm install -g @solana/pay
+```
+
+Verify the installation with:
+
+```bash
+pay --version
+```
+
+The toolchain will set up your address for you. Run the following to setup and
+topup your wallet:
+
+```bash
+pay setup
+pay topup
+```
+
 ## The x402 Protocol
 
 Agentic payments need a way for clients and servers to negotiate payment terms

apps/docs/content/docs/en/payments/subscriptions/meta.json

@@ -6,7 +6,8 @@
     "fixed-delegation",
     "recurring-delegation",
     "subscription-plan",
-    "close-subscription-authority"
+    "close-subscription-authority",
+    "pay-sh"
   ],
   "defaultOpen": false
 }

apps/docs/content/docs/en/payments/subscriptions/pay-sh.mdx

@@ -0,0 +1,98 @@
+---
+title: With Pay.sh
+description: Create subscriptions with Pay.sh.
+---
+
+You can set up subscriptions via Pay.sh by setting up a Pay client on your
+device or by setting up a Pay server. Install Pay with:
+
+```bash
+brew install pay
+```
+
+or
+
+```bash
+npm install -g @solana/pay
+```
+
+Verify the installation with:
+
+```bash
+pay --version
+```
+
+The toolchain will set up your address for you. Run the following to setup and
+topup your wallet:
+
+```bash
+pay setup
+pay topup
+```
+
+## Subscriptions as a client
+
+Users subscribe to subscription-gated API endpoints by invoking pay like normal.
+It is on the API to send the subscription details in the initial `402 Status`
+Response. Pay handles the subscription automatically, including instruction
+invokation on the Solana SPL Subscriptions Program.
+
+Users can manage their subscriptions using the following commands:
+
+```bash
+pay subscriptions                       # default: list + show available subcommands
+pay subscriptions list                  # same, scriptable
+pay subscriptions list --account work
+pay subscriptions list --network mainnet
+pay subscriptions list --json
+```
+
+You can learn more about managing your subscriptions as a user in the
+[Pay.sh > Using Pay > Manage Subscriptions docs](https://pay.sh/docs/using-pay/subscriptions).
+
+## Managing subscriptions as a provider (demo)
+
+Pay servers allow for configuring subscribers and their subscriptions for each
+endpoint. The following is an endpoint example that uses pay you can try with
+your project:
+
+```yaml
+# monthly.yml
+endpoints:
+  - method: GET
+    path: "api/v1/pro/feed"
+    resource: "pro-feed"
+    description: "Pro feed — monthly subscription, 30-day billing period."
+    subscription:
+      period: "30d"
+      price_usd: 9.99
+      currency: USDC
+```
+
+Pay handles subscriptions using the `subscription:` attribute in its `endpoints`
+YAML specification. This is opposed to the `metering:` attribute for pay-per-use
+endpoints.
+
+Starting the server in the above example creates an endpoint called
+`api/v1/pro/feed` that requires a user to make recurring payments of 9.99 USDC
+to it every 30 days.
+
+You can try it by running the following command:
+
+```bash
+pay --sandbox server start monthly.yml
+```
+
+You can test that the subscriptions work by running the following commands as a
+client on another terminal:
+
+```bash
+# First call — activates the subscription, $9.99 USDC charge settles.
+pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed
+
+# Same call within 30 days — no payment prompt, just the response.
+pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed
+```
+
+You can learn more about managing subscriptions on a Pay server via the
+[Pay.sh > Building with Pay > Subscriptions > YAML Specification docs](https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification).