# 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                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pingpay.gitbook.io/docs/pingpay-api/subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.