Subscriptions and autopay

A shop can ask a Heth.me user to approve recurring payments. The payer reviews and signs the conditions with their ordinary unlocked HethWallet. A separate email account or Customer Portal login is not needed. Payments debit the Heth account balance in the agreed currency and network.

For the payer

1. Open Settings → Subscriptions and autopay. New requests appear separately from existing subscriptions.
2. Open a request and check the shop, amount per payment, currency/network and billing period. A confirmation link opens the same screen. A locked wallet asks for its usual PIN and returns to the request.
3. Choose Enable subscription or Reject. Opening a link or receiving a notification never approves a subscription.
4. After approval, the first payment is scheduled. The list shows the amount, period and next payment date; while retrying a failed payment, it shows the next retry time.
5. Revoke the subscription to stop future charges. Revocation does not refund completed payments.

Approval records consent and schedules a payment; it does not mean that the payment has succeeded. Check the transaction status. The balance must be sufficient when a payment is executed.

How new requests are announced

For a recognized payer, the server sends a subscription-request push to registered devices, with a link to /subscriptions/confirm/<request_id>?env=<env>. An entry is also saved in the notification bell, even when no device can receive the push. Pending requests remain available in Settings → Subscriptions and autopay.

Installed PWAs use web push. Heth.me for iOS and Android, starting with version 1.0.0 (build 5), uses system notifications. Enable notifications in the wallet and allow them in your device settings. Tapping a subscription request opens its confirmation screen; a locked wallet first asks for the usual PIN or available passkey. Receiving or opening a notification does not approve the subscription. If a notification does not arrive, open the pending request list or the confirmation link from the shop.

For the shop

In HethWallet, open Business → Subscriptions and autopay. Enter the payer's wallet address, @username or Heth card number, a subscription name, the amount per payment, currency/network and period. Send the request, then copy its confirmation link. You can list your requests and cancel a request while it is still pending.

The operator must enable Heth subscriptions for the organization and configure a working payment route. Creating a request does not authorize a debit.

Create a request through the API

Use the shop's API key or its ordinary partner Bearer session. On app.heth.me, the organization is resolved from the host. A read-only key cannot create or cancel requests.

curl -X POST 'https://app.heth.me/api/v1/heth/subscription-requests' \
  -H "x-api-key: $HETH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "request_id": "b56b2c66-4ae5-4cb9-92ea-7a3297b72b55",
    "payer": "@alice",
    "description": "Monthly membership",
    "amount": "1000000",
    "currency": "USDT",
    "network": "ETH",
    "interval": "monthly",
    "period": 1,
    "env": "prod"
  }'

Field	Description	Type	Example
request_id	Unique idempotent UUID. Reuse it with identical terms when retrying the same request.	String	b56b2c66-4ae5-4cb9-92ea-7a3297b72b55
payer	Wallet address, username or Heth card number.	String	@alice
description	Subscription name, 1–250 characters without line breaks.	String	Monthly membership
amount	Positive integer in token minor units. For 6-decimal USDT, 1000000 means 1 USDT.	String	1000000
currency, network	Enabled token/network pair for the chosen environment. Networks: ETH, TRX, BASE.	String	USDT, ETH
interval	daily, weekly, monthly or yearly.	String	monthly
period	Number of intervals, 1–365; default 1.	Number	1
env	prod (default). Preserve this value when opening and confirming the request.	String	prod

HTTP 201 returns the request directly, including id, status, amount_decimals, confirm_url, expires_at, subscription_id and next_charge_at. Requests expire after seven days. A successful creation does not reveal whether the supplied payer exists; only the actual recipient can read and approve the request.

API operations

All paths below start with /api/v1. Shop operations require the shop's API key or partner Bearer session.

Method and path	Purpose
POST /heth/subscription-requests	Create a request.
GET /heth/subscription-requests?env=prod&limit=50	List the shop's requests in data and total.
POST /heth/subscription-requests/:id/cancel	Cancel a pending request; body {"env":"prod"}.

For the first page, omit page. Use page=1 for the next page, then increment it; limit controls the page size.

Wallet operations require the payer's ordinary wallet Bearer session. A shop's API key cannot approve for the payer.

Method and path	Purpose
GET /heth/subscriptions?env=prod&limit=50	Own subscriptions in data/total, pending requests in requests/requests_total.
GET /heth/subscription-requests/:id?env=prod	Read the addressed request and canonical signing message.
POST /heth/subscription-requests/:id/confirm	Approve with {"signature":"<wallet signature>","env":"prod"} after reviewing the exact conditions.
POST /heth/subscription-requests/:id/reject	Reject; body {"env":"prod"}.
POST /heth/subscriptions/:id/revoke-mandate	Stop future charges; body {"env":"prod"}.

The signature binds the shop, payer, organization, environment, description, amount and its scale, currency/network, interval and period, first-payment rule, nonce and expiry. Changing the conditions requires a new request and fresh consent. Retrying approval or a scheduled payment cannot debit the same period twice. API timestamps without a timezone suffix are UTC; the application displays device-local time.

Statuses and errors

Request statuses are pending, signed, rejected and expired. An approved request has a subscription_id. Track actual payment completion through the transaction API and configured webhooks.

401 means missing/invalid authentication; 403 means subscriptions are disabled or the API key is read-only. An inaccessible request returns 404. 422 indicates invalid terms, a reused UUID with different conditions, an invalid signature, or an expired/closed request. A shop cannot change the signed conditions of an active subscription without new payer consent.