WebsiteTwitterDiscord

⚡Subscriptions

Set up a crypto subscription in a few simple clicks

Set up a subscription page in USDC, SOL, ETH, BTC, or other digital assets with just a few clicks to collect recurring crypto payments on a set schedule. Whether you’re offering SaaS, Discord memberships, digital services, or any product requiring ongoing billing, Subscriptions streamline the entire process—from generating your payment to sending automated payment reminders to your customers, and handling subscription expirations.

Use Helio Pay Links or embed the Checkout Widget to accept subscription payments on your own website. Use webhooks to listen to events and confirm subscriptions in real time.

How it works

  • Initial Sign-Up

    • The customer makes their first payment to start the subscription.

    • A webhook is fired, indicating the subscription has been initiated.

  • Monthly Renewal

    • Customers receive email reminders with a “Renew Now” button before each billing cycle.

    • Reminder emails direct customers to a charge page where they simply complete payment with a single wallet confirmation—no extra steps needed.

  • Successful Renewal

    • Once payment is completed, Helio fires a renewal webhook.

    • Email reminders stop until the next billing cycle approaches.

  • Expired Subscription

    • If payment isn’t made by the renewal date (or within the grace period), the subscription expires.

    • A webhook payload notifies you that the subscription has ended.

Set up your subscription

Follow these steps to configure a Subscription in your Helio dashboard:

  1. Create or Edit a Pay Link: On your Helio Dashboard, navigate to Pay Links → Create Payment & select the Subscription template

  2. Configure Subscription: On Step 2, configure your payment, notifications, grace period & interval

    • Amount & Currency: Set the recurring charge amount in your preferred currency & blockchain

    • Billing Interval: select between monthly charges or annual charges (annual coming soon)

    • Email Reminders: select when reminders should start, customers are notified daily for the period of time configured

    • Grace Period: set a number of extra days (if any) during which the customer can still make the payment. The renewal date for customers stays the same

  3. Configure additional settings (optional): On Step 3, you can configure affiliate links, discounts, discord role distribution & more.

Please note: if any price adjustments are made after a subscription is live, the new price will apply to the next billing cycle.

Set up your webhooks

You can set up webhooks for your subscription payments to receive events when a user starts a new subscription, renews an existing one or when a subscription is ended.

NOTE: When using the production environment (app.hel.io), set your API endpoint to api.hel.io/v1 and generate API keys there. For the development environment, use api.dev.hel.io/v1 and generate API keys from app.dev.hel.io.

  • API Endpoint: https://api.hel.io/v1/webhook/paylink/subscription?apiKey=

  • HTTP Method: POST

  • Required Query Parameters: ?apiKey={Your public key here}

  • Required Headers: Authorization: Bearer {Your API Token here}

Request Body:

{
    "paylinkId": "{id}",
    "targetUrl": "{targetUrl}",
    "events": ["STARTED","RENEWED", "ENDED"]
}

  • “STARTED” – Triggered when a subscription begins after payment.

  • “RENEWED” – Triggered when a subscription is renewed.

  • “ENDED” – Triggered when a subscription expires or is canceled due to non-payment.

This is an example of a curl command to register a subscription webhook for paylinkID: 679bb9db7f3c16eb86bb1c67 triggered by the STARTED event upon transaction confirmation.

This sends a POST request to targetUrl: https://target-url.com/post-endpoint.

curl -X POST \
  https://api.hel.io/v1/webhook/paylink/subscription?apiKey=YOUR_API_KEY \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_SECRET' \
  -H 'cache-control: no-cache' \
  -d '
  {
     "paylinkId": "679bb9db7f3c16eb86bb1c67",
     "targetUrl": "targetUrl: https://target-url.com/post-endpoint",
     "events": ["STARTED"]
  }'

The response of this request will look like:

{
    "id": "679cb0a5eafd565eeab89605",
    "paylink": "679bb9db7f3c16eb86bb1c67",
    "company": "6683f4efc330474ede1f25aa",
    "targetUrl": "targetUrl: https://target-url.com/post-endpoint",
    "events": [
        "STARTED"
    ],
    "sharedToken": "ZtiSEjZsTNoczv8kvDgtSx5+YO017NOlM/mrqEMj2nnHXi+UfmCQvuqvZlI0eH3JJWrW1D3UDWM+GgK9sVfR0NNPIMwWNV+jcFehjDIMlVq05Ahf2/5tUT/W7qqiHWZy"
}

A unique token generated at webhook creation is included with each webhook as authorization: Bearer SHARED_TOKEN, verifying the webhook source as Helio.

Note: Retain this token to authenticate and delete web hooks if needed.

Upon successful payment on Pay Link 679bc67238ad367780fc7cf1, the targetUrl will receive an HTTP [POST] request with the following payload:

{
  "event": "STARTED",
  "email": "tim@hel.io",
  "subscriptionState": "NEW",
  "subscriptionId": "67a2398e353a885e45cc7651",
  "transactionObject": {
    "id": "67a239887e23092b632feded",
    "paylinkId": "67a23795353a885e45cc6d6a",
    "fee": "2000",
    "quantity": 1,
    "createdAt": "2025-02-04T16:00:08.368Z",
    "paymentType": "PAYLINK",
    "meta": {
      "id": "67a239887e23092b632fedeb",
      "amount": "98000",
      "senderPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
      "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
      "transactionType": "PAYLINK",
      "customerDetails": {
        "email": "jesse@hel.io",
        "discordUser": null
      },
      "productDetails": null,
      "additionalProductDetails": [],
      "transactionSignature": "5AmMWzAjCLnYo36xyDHRDWoeAtF3113b6FA1RJiNRidmAuUHRYyQ2dkJuTTPaNUpurSzMEyBimu3GbRLVyHrwSA1",
      "transactionStatus": "SUCCESS",
      "splitRevenue": false,
      "remainingAccounts": [],
      "totalAmount": "98000",
      "affiliateAmount": "0",
      "tokenQuote": {
        "from": "USDC",
        "fromAmountDecimal": "0.1",
        "to": "USDC",
        "toAmountMinimal": "100000"
      },
      "shopifyPaymentDetails": null,
      "submitGeolocation": "GB",
      "currency": {
        "id": "63430c8348c610068bcdc482",
        "blockchain": null
      }
    }
  }

Note: When you create or list Pay Link webhooks, a sharedToken is generated. This token is sent to your endpoint as authorization: Bearer SHARED_TOKEN to validate that the webhook originates from Helio.

Retrieve all subscriptions in your account

NOTE: When using the production environment (app.hel.io), set your API endpoint to api.hel.io/v1 and generate API keys there. For the development environment, use api.dev.hel.io/v1 and generate API keys from app.dev.hel.io.

You can retrieve all subscriptions set up under your account, with the added ability to filter by Pay Link ID and email.

  • API Endpoint: https://api.hel.io/v1/subscriptions

  • HTTP Method: GET

  • Required Headers: Authorization: Bearer {SECRET_API_KEY}

Query Parameters

Parameter
Type
Required
Description

apiKey

String

Yes

Your Public API Key

paylink

String

No

The Pay Link ID of the subscription

email

String

No

The email used to sign up for the subscription

Example URL with Query Parameters

https://api.hel.io/v1/subscriptions?apiKey=0VZWmr3rbi~Z_BN-urmGGl90bYZ8D5LLAu7QCZ3xIeQmQZo.9gEFm8M1AMaeev1Y&email=test@hel.io&paylink=67a0d1ed18c700e1cda9ebf6

Sample Response

{
        "id": "67a1e53e10905ce3927d6f1a",
        "status": "EXPIRED",
        "email": "test@hel.io",
        "renewalDate": "2025-03-04T00:00:00.000Z",
        "createdAt": "2025-02-04T10:00:30.259Z",
        "transactions": [
            {
                "id": "67a1e53810905ce3927d6e46",
                "paylinkId": "67a0d1ed18c700e1cda9ebf6",
                "fee": "2000",
                "quantity": 1,
                "createdAt": "2025-02-04T10:00:24.839Z",
                "paymentType": "PAYLINK",
                "meta": {
                    "id": "67a1e53810905ce3927d6e44",
                    "amount": "98000",
                    "senderPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                    "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                    "transactionType": "PAYLINK",
                    "customerDetails": {
                        "email": "jkbaffourr@gmail.com",
                        "discordUser": null
                    },
                    "productDetails": null,
                    "additionalProductDetails": [],
                    "transactionSignature": "5QCkdQSeRd3sHs9etreVn1qR7RGcGrsQoHm6vw2ddSXYjSafrkSpPg3uCzv7D2eKg4toBPPyzyAxDUZDBPyGXBoD",
                    "transactionStatus": "SUCCESS",
                    "splitRevenue": false,
                    "remainingAccounts": [],
                    "totalAmount": "98000",
                    "affiliateAmount": "0",
                    "tokenQuote": {
                        "from": "USDC",
                        "fromAmountDecimal": "0.1",
                        "to": "USDC",
                        "toAmountMinimal": "100000"
                    },
                    "shopifyPaymentDetails": null,
                    "submitGeolocation": "GB"
                }
            }
        ]
    },
    {
        "id": "67a1e561b49e0bc0ea87ca27",
        "status": "ACTIVE",
        "email": "alan@hel.io",
        "renewalDate": "2025-03-04T00:00:00.000Z",
        "createdAt": "2025-02-04T10:01:05.271Z",
        "transactions": [
            {
                "id": "67a1e55ab49e0bc0ea87c953",
                "paylinkId": "67a0d1ed18c700e1cda9ebf6",
                "fee": "2000",
                "quantity": 1,
                "createdAt": "2025-02-04T10:00:58.917Z",
                "paymentType": "PAYLINK",
                "meta": {
                    "id": "67a1e55ab49e0bc0ea87c951",
                    "amount": "98000",
                    "senderPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                    "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                    "transactionType": "PAYLINK",
                    "customerDetails": {
                        "email": "jb18xpsn@gmail.com",
                        "discordUser": null
                    },
                    "productDetails": null,
                    "additionalProductDetails": [],
                    "transactionSignature": "62TbrxTXQkqbGrVGLtFTLV3ReMgP85fGhrFnAmy1ME5svbX19TJc4fzUnKr6Umjyrz3ma153x4KNy5F6XosGspyx",
                    "transactionStatus": "SUCCESS",
                    "splitRevenue": false,
                    "remainingAccounts": [],
                    "totalAmount": "98000",
                    "affiliateAmount": "0",
                    "tokenQuote": {
                        "from": "USDC",
                        "fromAmountDecimal": "0.1",
                        "to": "USDC",
                        "toAmountMinimal": "100000"
                    },
                    "shopifyPaymentDetails": null,
                    "submitGeolocation": "GB"
                }
            }
        ]
    }
]

Query a specific subscription

NOTE: When using the production environment (app.hel.io), set your API endpoint to api.hel.io/v1 and generate API keys there. For the development environment, use api.dev.hel.io/v1 and generate API keys from app.dev.hel.io.

You can query a specific subscription to view its status or additional details. This is done using the subscription ID, which can be retrieved via the https://api.hel.io/v1/subscriptions endpoint.

  • API Endpoint: https://api.hel.io/v1/subscriptions/{id}

  • HTTP Method: GET

  • Required Headers: Authorization: Bearer {SECRET_API_KEY}

  • Required Query Parameters: ?apiKey={Your public key here}

  • Required Path: id

id refers to the subscription ID, which can be retrieved using the https://api.hel.io/v1/subscriptions endpoint here.

Example URL with Query Parameters

https://api.hel.io/v1/subscriptions/67a0d2ea18c700e1cda9f1b8?apiKey=0VZWmr3rbi~Z_BN-urmGGl90bYZ8D5LLAu7QCZ3xIeQmQZo.9gEFm8M1AMaeev1Y

Sample Response

{
    "id": "67a0d2ea18c700e1cda9f1b8",
    "status": "ACTIVE",
    "email": "test@hel.io",
    "renewalDate": "2025-03-03T00:00:00.000Z",
    "createdAt": "2025-02-03T14:30:02.287Z",
    "transactions": [
        {
            "id": "67a0d2e318c700e1cda9f09d",
            "paylinkId": "67a0d1ed18c700e1cda9ebf6",
            "fee": "2000",
            "quantity": 1,
            "createdAt": "2025-02-03T14:29:55.911Z",
            "paymentType": "PAYLINK",
            "meta": {
                "id": "67a0d2e318c700e1cda9f09b",
                "amount": "98000",
                "senderPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                "transactionType": "PAYLINK",
                "customerDetails": {
                    "email": "jesse@hel.io",
                    "discordUser": null
                },
                "productDetails": null,
                "additionalProductDetails": [],
                "transactionSignature": "5UtTTc2rph145g6YRCZv5no6dfQBAVfp3Rw4KvQXpBPJ1BBu2F8JJBd7uUGoxVN7GAjjKaDPMb3VynXj4FrUbRv2",
                "transactionStatus": "SUCCESS",
                "splitRevenue": false,
                "remainingAccounts": [],
                "totalAmount": "98000",
                "totalAmountAsUSD": "98000",
                "affiliateAmount": "0",
                "tokenQuote": {
                    "from": "USDC",
                    "fromAmountDecimal": "0.1",
                    "to": "USDC",
                    "toAmountMinimal": "100000"
                },
                "shopifyPaymentDetails": null,
                "submitGeolocation": "GB"
            }
        }
    ]
}
PreviousPre-SalesNextBlinks

Last updated