Create Pay Links via API

Create your Helio Pay Links programatically

ℹ️ To see a code example, check out our dev examples repository.

You can also create "Charges" via API for single-use checkout pages

Creating a Pay Link via API

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/paylink/create/api-key

• HTTP Method: POST

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

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

Required request body:

{
  "template": "OTHER",
  "name": "Your paylink name here",
  "price": "1000000", /* price is int64 represented by the base units of each currency, e.g. "price": "1000000" = 1 USDC*/
  "pricingCurrency": "6340313846e4f91b8abc519b", /* currency ID to price it in - can be a fiat currency */
  "features": {}, /* this must be set, even if empty */
  "recipients": [
    {
      "walletId": "YOUR_WALLET_ID",
      "currencyId": "6340313846e4f91b8abc519b"
    }
  ]
}

All the fields in the example request body are mandatory.

• Configure multiple recipients and currencies if needed. The recipient currency can differ from the pricing currency.

  • For instance, you could price the link in EUR (e.g., €5) while accepting USDC or USDT as recipient currencies.

Example query:

curl --location 'https://api.hel.io/v1/paylink/create/api-key?apiKey=<YOUR_PUBLIC_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
--data '{
    "name": "Paylink Name Example",
    "description": "Paylink Description Example",
    "pricingCurrency": "6340313846e4f91b8abc519b",
    "currency": "SOL",
    "recipients": [
        {
            "currencyId": "6340313846e4f91b8abc519b",
            "walletId": "YOUR_WALLET_ID"
        }
    ],
  "price": "1",
  "features": {}
}'

From the following example replace: YOUR_PUBLIC_API_KEY, YOUR_SECRET_API_KEY, YOUR_WALLET_ID (and the pricing/recipient currency IDs) with the values you collected in the previous step.

For the response body please check the response body section below.

Note for this basic example pricingCurrency and currencyId are the same, but they don't have to be. For example, you can price the Pay Link in USDC and receive SOL, Helio takes care of the conversions on your behalf

Advanced use cases

For advanced use cases, here is the full list of possible request body options.

{
   name: string; /* set the pay link name */

   features: {
     requireEmail?: boolean; /* require buyer to submit an email */
     requireDiscordUsername?: boolean; /* require buyer to submit an email */
     requireDiscordLogin?: boolean; /* require buyer to login with discord */
     requireFullName?: boolean; /* require buyer to enter their full name */
     requireTwitterUsername?: boolean; /* require buyer to enter their X username */
     requireCountry?: boolean; /* require buyer to enter their country */
     requireDeliveryAddress?: boolean; /* require buyer to enter their X username */
     requirePhoneNumber?: boolean; /* require buyer to enter their X username */
     requireProductDetails?: boolean; /* require additioanal details from the buyer */
     requireMaxTransactions?: boolean; /* enable a limit on the number of transactions */
     requireNftGate?: boolean; /* require an NFT gate for access */
     requireDiscordAuth?: boolean; /* require buyer to enter their X username */
     requireAccessCode?: boolean; /* require buyer to enter access code to use paylink */
     requireFixedCurrency?: boolean; /* restrict transactions to a fixed currency */
     canSwapTokens?: boolean;  /* enable token swaps on your pay link */
     isHelioPlay?: boolean; /* enable Helio Play functionality */
     isTransparentWallet?: boolean;
     nftDropEnabled?: boolean; /* enable NFT drop functionality */
     requireTradingViewUsername?: boolean; /* require buyer to submit trading view username */
     allowAffiliate?: boolean; /* enable affiliate commissions */
     enableCountdown?: boolean; /* enable countdown on your pay link */
     isSubscription?: boolean; /* enable subscriptions on your pay link*/
     isEventEnabled?: boolean; /* enable event-related payments */
     splitRevenue?: boolean; /* enable revenue sharing between multiple recipients */
     splitEqually?: boolean; /* split revenue equally among recipients */
     canChangeQuantity?: boolean; /* enable users to change quantity on the pay link */
     requireQuantityLimits?: boolean; /* set quantity limits on purchases */
     canChangePrice?: boolean; /* enable users to set their own price */
     isEscrowed?: boolean; /* enable escrow functionality for transactions */
     shouldRedirectOnSuccess?: boolean; /* enable redirecting users after a successful transaction */
     showDiscountCode?: boolean; /* display a discount code field at checkout */
     requireDiscordQuantityLimit?: boolean; /* enable a quantity limit per discord user */
     requireAllowlist?: boolean; /* enable an allowlist */
     requireAirdrop?: boolean; /* enable a cNFT airdrop */
   };

   price?: string; /* set the pay link price */

   pricingCurrency?: string; /* set the currency for the pay link */

   recipients?: { /* set your receipient wallets */
      currencyId: string;
      walletId: string;
   }[];

   description?: string; /* set your paylink description */

   template?: 'PRODUCT' | 'SUBSCRIPTION' | 'PRE_SALE' | 'SINGLE_NFT' | 'VIDEO' | 'DISCORD_MEMBERSHIP' | 'INVOICE' | 'EMBEDDED' | 'LINK_OR_FILE' | 'TRADING_VIEW' | 'EVENT' | 'OTHER' | 'LEGACY';

   normalizedPrice?: string;

   notifySenderByEmail?: boolean = false;  /* Enable email notifications to the buyer */

   notifyReceiverByEmail?: boolean = false; /* enable email notifications to the seller */

   addDiscordRole?: boolean = false; /* assign a discord role after purchase */

   discordRoleIds?: string[]; /* list of Discord role id's to assign */

   disabled?: boolean; /* disable the pay link */

   dynamic?: boolean; /* set the pay link as dynamic or static */

   content?: { /* set the content for your paylink */
     text?: string;
     mediaUrl?: string;
     mediaAttachmentId?: string;
   };

   maxTransactions?: number; /* set the maximum number of transactions allowed on the pay link*/


   product?: { { /* define the additional product details */
     name: string;
     description: string;
     type: 'TEXT' | 'SELECTOR';
   };

   nftCollectionAddress?: string; /* set the nft collection address */

   discordAuthDetails?: { /* configure discord authentication */
     serverId: string; /* discord server id */
     roleId: string; /* discord role id */
   }[];

   nftDrop?: { /* configure NFT drop settings */
     mintAddresses: string[] /* list of mint addresses */
   };

   accessCodeAuthProperties?: { { /* set access code authentication */
     accessCode: string;
   };

   fixedCurrency?: { /* set fixed currency payment details */
     currency: string;
     price: number;
   };

   tradingViewIndicators?: { /* set your trading view indicators */
     id: string;
     url: string;
     name: string;
   }[];

   affiliateDetails?: { /* set the affiliate percentage for your Pay Link */
     bps: number;
   };

   eventDetails?: { /* set event-specific details */
     datetime: Date;
     location?: string;
   };

   countdownDetails?: { /* set start and end time of your pay link */
     startDatetime: Date;
     endDatetime?: Date;
   };

   splitWallets?: { /* enable payment to be split between multiple wallets */
     address: string;
     percent?: number;
     sharePercent?: number;
   }[];
   
   subscriptionDetails: { /* set the details of your subscription  */
    renewalReminders: 0, /* set how many renewal reminders will be sent  */
    gracePeriod: 0, /* set the grace period once the subscription expires   */
    annualDiscountBps: 0, /* "discount in basis points for an annual subscription." */
    interval: "MONTH" /* set the interval, "MONTH" or "ANNUAL" */
  };

   discountCodes?: { /* set discount codes for your pay link */
     percent: number;
     token: string;
     prId?: string;
     id?: string;
     tokenType: 'CODE' | 'NFT_COLLECTION';
   }[];

   limitSaleType?: 'TRANSACTION' | 'DISCORD_ID'; /* set sale limit type */

   minQuantity?: number; /* set the minimum quantity on your pay link */

   maxQuantity?: number; /* set the maximum quantity on your pay link */

   helioPlayProperties?: { /* set the maximum quantity on your pay link */
     durationSec?: number;
     previewAttachmentId?: string;
     media: {
       type: 'VIDEO';
       hosted: boolean;
     };
   };
   
   redirectUrl?: string; /* set a URL to redirect users to after a successful transaction on your pay link */
   
   airdropDetailsId?: string; /* set an ID for the airdrop details */
}

Response body example

{
  "id": "656de2de971d6c8e978293bf",
  "template": "OTHER",
  "disabled": false,
  "inactive": false,
  "notifySenderByEmail": false,
  "notifyReceiverByEmail": false,
  "addDiscordRole": false,
  "helioPlayProperties": null,
  "features": {
    "canChangeQuantity": false,
    "canChangePrice": false,
    "requireQuantityLimits": false,
    "requireCountry": false,
    "requireEmail": false,
    "requireDeliveryAddress": false,
    "requireDiscordUsername": false,
    "requireDiscordLogin": false,
    "requireFullName": false,
    "requirePhoneNumber": false,
    "requireTwitterUsername": false,
    "requireProductDetails": false,
    "requireMaxTransactions": false,
    "requireNftGate": false,
    "requireDiscordAuth": false,
    "requireAccessCode": false,
    "splitRevenue": false,
    "splitEqually": false,
    "requireFixedCurrency": false,
    "canSwapTokens": false,
    "isHelioPlay": false,
    "isTransparentWallet": false,
    "nftDropEnabled": false,
    "showDiscountCode": false,
    "isEscrowed": false,
    "requireDiscordQuantityLimit": false,
    "requireAllowlist": false,
    "requireTradingViewUsername": false,
    "allowAffiliate": false,
    "requireAirdrop": false,
    "isEventEnabled": false,
    "enableCountdown": false,
    "shouldRedirectOnSuccess": false
  },
  "name": "pay link name",
  "discordAuthDetails": [],
  "dynamic": false,
  "affiliateDetails": null,
  "price": "100000",
  "content": {},
  "creator": {
    "id": "63bfb6f92f9a086a381c4616",
    "email": "",
    "name": "",
    "isDisabled": false,
    "kycVerified": true,
    "helioVerified": true,
    "platformDetails": null
  },
  "company": {
    "id": "63bfb6f92f9a086a381c4618",
    "name": "",
    "email": "",
    "websiteUrl": "",
    "discordUsername": "",
    "address": "",
    "phoneNumber": "",
    "escrowFunds": false,
    "tradingViewDetails": "",
    "twitterUsername": "",
    "twitterConfirmed": true
  },
  "currency": {
    "id": "63430c8348c610068bcdc482",
    "name": "USD Coin",
    "decimals": 6,
    "order": 1,
    "mintAddress": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "coinMarketCapId": 3408,
    "symbol": "USDC",
    "symbolPrefix": "$",
    "type": "DIGITAL",
    "iconUrl": "USDC.svg",
    "features": ["PAYMENT_PRICING", "PAYMENT_RECIPIENT"],
    "blockchain": {
      "id": "63430c8348c610068bcdc43c",
      "name": "SOL",
      "symbol": "SOL",
      "engine": {
        "id": "63b574b9d07b6f6f21c13eb2",
        "type": "SOL"
      }
    }
  },
  "wallet": {
    "id": "63bfb6f92f9a086a381c4612",
    "publicKey": "9PTAZwj9qeet6bCAai6aoTg1phfgJonBwKvy8btQJMxR",
    "btcProperties": null
  },
  "recipients": [
    {
      "currency": {
        "id": "63430c8348c610068bcdc482",
        "name": "USD Coin",
        "decimals": 6,
        "order": 1,
        "mintAddress": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        "coinMarketCapId": 3408,
        "symbol": "USDC",
        "symbolPrefix": "$",
        "type": "DIGITAL",
        "iconUrl": "USDC.svg",
        "features": ["PAYMENT_PRICING", "PAYMENT_RECIPIENT"],
        "blockchain": {
          "id": "63430c8348c610068bcdc43c",
          "name": "SOL",
          "symbol": "SOL",
          "engine": {
            "id": "63b574b9d07b6f6f21c13eb2",
            "type": "SOL"
          }
        }
      },
      "wallet": {
        "id": "63bfb6f92f9a086a381c4612",
        "publicKey": "9PTAZwj9qeet6bCAai6aoTg1phfgJonBwKvy8btQJMxR",
        "btcProperties": null,
        "blockchainEngine": {
          "id": "63b574b9d07b6f6f21c13eb2",
          "type": "SOL"
        }
      }
    }
  ],
  "volume": 0,
  "sales": "0",
  "product": null,
  "discountCodes": [],
  "discordRoleIds": [],
  "pricingCurrency": {
    "id": "63430c8348c610068bcdc482",
    "name": "USD Coin",
    "decimals": 6,
    "order": 1,
    "mintAddress": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
    "coinMarketCapId": 3408,
    "symbol": "USDC",
    "symbolPrefix": "$",
    "type": "DIGITAL",
    "iconUrl": "USDC.svg",
    "features": ["PAYMENT_PRICING", "PAYMENT_RECIPIENT"],
    "blockchain": {
      "id": "63430c8348c610068bcdc43c",
      "name": "SOL",
      "symbol": "SOL",
      "engine": {
        "id": "63b574b9d07b6f6f21c13eb2",
        "type": "SOL"
      }
    }
  },
  "redirectUrl": ""
}

Single use Pay Links with maxTransactions as 1

If you would like to a single-use payments, we recommend using charges. Alternatively you can set a limit of 1 on your Pay Link using the following config:

{   "name": "Paylink with 1 limit",
    "description": "test desciption",
    "pricingCurrency": "6340313846e4f91b8abc5195",
    "currency": "SOL",
    "recipients": [
        {
            "currencyId": "6340313846e4f91b8abc5195",
            "walletId": "your wallet id"
        }
    ],
  "price": "10000",
  "maxTransactions": 1,
  "features": {
    "requireMaxTransactions": true
  }
}