> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-api/subscriptions.md).

# Subscriptions

Ping Subscriptions lets merchants collect recurring crypto payments on NEAR using signed intents. Subscribers approve all future payments upfront by signing NEAR intents, and Ping releases them on schedule — no repeated wallet approvals needed.

### How It Works

1. **Merchant creates a subscription session** via the API (plan name, amount, interval, number of periods)
2. **Subscriber opens the session URL** and connects their NEAR wallet
3. **Subscriber signs all intents at once** — one per payment period (e.g. 12 intents for a monthly plan with 12 periods)
4. **Ping activates the subscription** and releases payments automatically on the defined schedule
5. **Merchant receives webhooks** for each payment release, failure, cancellation, or completion

### Current Limitations (V1)

| Constraint     | Details                         |
| -------------- | ------------------------------- |
| Asset          | USDC on NEAR only               |
| Max periods    | 12 payments per subscription    |
| Min interval   | 60 seconds (useful for testing) |
| Session expiry | 1 hour after creation           |

### Prerequisites

* A Ping merchant account with an API key
* A NEAR wallet address configured as your payout address
* **Your payout address must hold assets in `intents.near`** — the NEAR intents contract requires the recipient to have previously interacted with it. If your address has never deposited into `intents.near`, subscription payments will fail silently. See NEAR Intents Setup for details.

### Quick Start

```bash
# 1. Create a subscription session
curl -X POST https://pay.pingpay.io/api/rpc/subscriptions/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Pro Plan",
    "amount": "5000000",
    "asset": { "chain": "near", "symbol": "USDC" },
    "interval": "MONTHLY",
    "totalPeriods": 12,
    "successUrl": "https://yourapp.com/subscribed",
    "cancelUrl": "https://yourapp.com/cancelled"
  }'

# 2. Redirect your customer to the returned sessionUrl
# 3. After subscription activates, you'll receive webhooks for each payment
```

### Docs Index

| Page                   | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| NEAR Intents Setup     | How to prepare your NEAR wallet for receiving subscription payments |
| API Reference          | Full endpoint documentation with request/response examples          |
| Subscription Lifecycle | States, transitions, and what triggers each                         |
| Webhooks               | Webhook events, payloads, and verification                          |
| Wallet UX & Signing    | What subscribers experience and known UX limitations                |
| Integration Guide      | Step-by-step merchant integration with code examples                |