> 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/wallet-ux-and-signing.md).

# Wallet UX & Signing

This page explains what subscribers experience when activating a subscription, including current UX limitations and what we're doing about them.

### The Signing Flow

When a subscriber activates a Ping subscription, they need to sign one NEAR intent per payment period. For example, a 12-month subscription requires signing 12 intents.

#### What the Subscriber Sees

1. **Connect wallet** — Standard NEAR wallet connection (e.g. MyNearWallet, Meteor, HERE Wallet)
2. **Review plan** — Subscription name, amount, interval, and total periods displayed
3. **Sign intents** — A progress bar shows signing progress (e.g. "Signing 3 of 12...")
4. **Confirmation** — Subscription activated, redirected to success URL

#### The Multi-Popup Problem

**This is the biggest UX friction point in V1.**

Each intent requires a separate wallet signature. Depending on the wallet, this means:

* **Multiple popup windows** — The subscriber may see 12 consecutive wallet popups for a 12-month plan
* **Browser popup blockers** — Some browsers block rapid sequential popups, interrupting the flow
* **User fatigue** — Signing 12 transactions feels tedious compared to a single "Subscribe" button

#### What We're Doing About It

We are actively working with NEAR wallet teams to improve this experience:

* **Batch signing** — Working with wallet providers to support signing multiple intents in a single approval
* **Session keys** — Exploring NEAR session keys that could allow Ping to sign on behalf of the subscriber for pre-approved amounts
* **Fewer periods, longer intervals** — In the meantime, consider using fewer total periods (e.g. quarterly billing instead of monthly) to reduce signing friction

> **We expect significant UX improvements here as wallet teams roll out batch signing support. This is a top priority for us and the NEAR wallet ecosystem.**

### Intent Structure

Each signed intent authorizes a single future payment:

```json
{
  "signer_id": "alice.near",
  "deadline": "2026-05-21T12:00:00.000Z",
  "intents": [
    {
      "intent": "transfer",
      "receiver_id": "merchant.near",
      "tokens": {
        "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": "5000000"
      }
    }
  ]
}
```

Key points:

* Each intent has its own **deadline** — set to `startTime + (periodIndex + 2) * intervalSecs`, giving a buffer window
* Intents are signed with **NEP-413** standard (NEAR's off-chain message signing)
* Signatures use **Ed25519** and are encoded as `ed25519:base58`
* The `recipient` field in the NEP-413 payload is always `intents.near`

### Subscriber Requirements

| Requirement     | Details                                                                 |
| --------------- | ----------------------------------------------------------------------- |
| NEAR wallet     | Any wallet supporting NEP-413 signing                                   |
| USDC balance    | Sufficient USDC on NEAR for each payment period                         |
| Ongoing balance | Subscriber must maintain USDC balance through the subscription duration |

### Tips for Merchants

1. **Keep `totalPeriods` reasonable** — Fewer periods = fewer signatures = better UX. Consider quarterly or semi-annual billing.
2. **Set clear expectations** — Tell subscribers upfront they'll need to sign multiple transactions.
3. **Use `successUrl`** — Redirect subscribers back to your app after activation for a smooth experience.
4. **Test with short intervals** — Use `{ "customSecs": 120 }` (2-minute intervals) during development to quickly verify the full lifecycle.
5. **Handle `PAYMENT_FAILED`** — If a subscriber's balance runs out, you'll get a webhook. Reach out to them to top up.