Skip to content

Commit 618f20c

Browse files
datasalarymandatasalaryman
authored
feat: add Pay.sh pages for Accept Payments and Subscriptions (#1525)
1 parent 201feed commit 618f20c

5 files changed

Lines changed: 225 additions & 2 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"title": "Accept Payments",
3-
"pages": ["payment-button", "verification-tools", "indexing"],
3+
"pages": ["payment-button", "verification-tools", "indexing", "pay-sh"],
44
"defaultOpen": false
55
}

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: With Pay.sh
3+
description: Accept payments with Pay.sh.
4+
---
5+
6+
You can accept payments on API requests via Pay.sh by setting up a Pay server.
7+
Install Pay with:
8+
9+
```bash
10+
brew install pay
11+
```
12+
13+
or
14+
15+
```bash
16+
npm install -g @solana/pay
17+
```
18+
19+
Verify the installation with:
20+
21+
```bash
22+
pay --version
23+
```
24+
25+
The toolchain will set up your address for you. Run the following to setup and
26+
topup your wallet:
27+
28+
```bash
29+
pay setup
30+
```
31+
32+
## Setting up the demo server
33+
34+
You can start accepting payments by starting your server. You can see a demo
35+
server in action with:
36+
37+
```bash
38+
pay server demo
39+
```
40+
41+
This does two things. It starts a live Pay server which you can query via HTTP
42+
request, and it generates a `pay-demo.yml` file in your current directory.
43+
44+
All API routes are configured via the `endpoints` YAML config. In order to
45+
accept payments, you have to add a `metering:` attribute. The
46+
`/api/v1/reports/usage` route has been done as an example for you:
47+
48+
```yaml
49+
endpoints:
50+
- method: GET
51+
path: "api/v1/reports/usage"
52+
resource: "reports"
53+
description: "Usage report — flat fee, no splits."
54+
metering:
55+
dimensions:
56+
- direction: usage
57+
unit: requests
58+
scale: 1
59+
tiers:
60+
- price_usd: 0.01
61+
```
62+
63+
You can test that the payments work by running the following command as a client
64+
on another terminal:
65+
66+
```bash
67+
pay --sandbox curl http://127.0.0.1:1402/api/v1/reports/usage
68+
```
69+
70+
You can learn more about how to define pricing in the
71+
[Pay.sh Building with Pay > Pricing docs](https://pay.sh/docs/building-with-pay/pricing)
72+
73+
Learn more about setting up Pay.sh in production in the
74+
[Pay.sh Configuration docs](https://pay.sh/docs/toolchain/configuration).

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,31 @@ APIs without provider accounts or API keys. When an API returns an MPP or x402
3333
`402 Payment Required` challenge, `pay` asks your local wallet to approve
3434
signing.
3535

36+
You can install Pay with:
37+
38+
```bash
39+
brew install pay
40+
```
41+
42+
or
43+
44+
```bash
45+
npm install -g @solana/pay
46+
```
47+
48+
Verify the installation with:
49+
50+
```bash
51+
pay --version
52+
```
53+
54+
The toolchain will set up your address for you. Run the following to setup and
55+
topup your wallet:
56+
57+
```bash
58+
pay setup
59+
```
60+
3661
## The x402 Protocol
3762

3863
Agentic payments need a way for clients and servers to negotiate payment terms

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
"fixed-delegation",
77
"recurring-delegation",
88
"subscription-plan",
9-
"close-subscription-authority"
9+
"close-subscription-authority",
10+
"pay-sh"
1011
],
1112
"defaultOpen": false
1213
}

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: With Pay.sh
3+
description: Create subscriptions with Pay.sh.
4+
---
5+
6+
You can set up subscriptions via Pay.sh by setting up a Pay client on your
7+
device or by setting up a Pay server. Install Pay with:
8+
9+
```bash
10+
brew install pay
11+
```
12+
13+
or
14+
15+
```bash
16+
npm install -g @solana/pay
17+
```
18+
19+
Verify the installation with:
20+
21+
```bash
22+
pay --version
23+
```
24+
25+
The toolchain will set up your address for you. Run the following to setup and
26+
topup your wallet:
27+
28+
```bash
29+
pay setup
30+
```
31+
32+
## Subscriptions as a client
33+
34+
Users subscribe to subscription-gated API endpoints by invoking pay like normal.
35+
It is on the API to send the subscription details in the initial `402 Status`
36+
Response. Pay handles the subscription automatically, including instruction
37+
invocation on the Solana SPL Subscriptions Program.
38+
39+
Users can manage their subscriptions using the following commands:
40+
41+
```bash
42+
pay subscriptions # default: list + show available subcommands
43+
pay subscriptions list # same, scriptable
44+
pay subscriptions list --network mainnet
45+
pay subscriptions list --json
46+
```
47+
48+
You can learn more about managing your subscriptions as a user in the
49+
[Pay.sh > Using Pay > Manage Subscriptions docs](https://pay.sh/docs/using-pay/subscriptions).
50+
51+
## Managing subscriptions as a provider (demo)
52+
53+
Pay servers allow for configuring subscribers and their subscriptions for each
54+
endpoint. The following is an endpoint example that uses pay you can try with
55+
your project:
56+
57+
```yaml
58+
# monthly.yml
59+
name: Subscriptions Example
60+
subdomain: subscriptions-example
61+
title: "Subscription Example"
62+
description: "Demo Subscriptions"
63+
category: ai_ml
64+
version: v1
65+
routing:
66+
type: respond
67+
operator:
68+
currencies:
69+
usd: ["USDC", "USDT", "CASH"]
70+
network: "localnet"
71+
fee_payer: true
72+
challenge_binding_secret: d858d9104afd728f58a1f73d806dd75d8f32ebd37c9707145816b490e8631d41
73+
# insert your own challenge_binding_secret here. use `openssl rand -hex 32`
74+
75+
endpoints:
76+
- method: GET
77+
path: "api/v1/pro/feed"
78+
resource: "pro-feed"
79+
description: "Pro feed — monthly subscription, 30-day billing period."
80+
subscription:
81+
period: "30d"
82+
price_usd: 9.99
83+
currency: USDC
84+
plan_id_numeric: 1
85+
```
86+
87+
Pay handles subscriptions using the `subscription:` attribute in its `endpoints`
88+
YAML specification. This is opposed to the `metering:` attribute for pay-per-use
89+
endpoints.
90+
91+
Starting the server in the above example creates an endpoint called
92+
`api/v1/pro/feed` that requires a user to make recurring payments of 9.99 USDC
93+
to it every 30 days.
94+
95+
You can try it by running the following command:
96+
97+
```bash
98+
pay server start monthly.yml
99+
```
100+
101+
Running this command will prompt you to create a plan. This creates a plan and
102+
updates the yml file. If you're going to use it again, remember the plan address
103+
and use that in your config as you're making changes.
104+
105+
You can test that the subscriptions work by running the following commands as a
106+
client on another terminal:
107+
108+
```bash
109+
# First call — activates the subscription, $9.99 USDC charge settles.
110+
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed
111+
112+
# Same call within 30 days — no payment prompt, just the response.
113+
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed
114+
```
115+
116+
You should see an OK status as a response like this:
117+
118+
```json
119+
{ "status": "ok" }
120+
```
121+
122+
You can learn more about managing subscriptions on a Pay server via the
123+
[Pay.sh > Building with Pay > Subscriptions > YAML Specification docs](https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification).

0 commit comments

Comments
 (0)