Overview

When creating a Pay Link via API the following request body is required

{
  "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"
    }
  ]
}

Configure multiple recipients and currencies if needed. The recipient currency can differ from the pricing currency. You can retrieve the currencyId from this endpoint, and see here for how to retrieve your walletId.
- 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": {}
}'

Note: In 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 handles the conversions on your behalf.

Token swaps

With token swaps enabled, customers can pay using supported tokens; funds are swapped and settled into USDC on the network(s) you choose via each recipient’s currencyId (0.25% swap fee). Use features.canSwapTokens set to true. For the full product explanation, see No Code — Token Swaps. Resolve each currencyId from Get All Currencies and each walletId from Get wallets or the dashboard.

USDC on Solana only

All swapped proceeds settle to USDC on Solana (single Solana USDC recipient).

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": "Swaps example (Solana USDC)",
  "price": "1000000",
  "pricingCurrency": "6340313846e4f91b8abc519b",
  "features": { "canSwapTokens": true },
  "recipients":[
      {
         "walletId":"YOUR_SOLANA_WALLET_ID", // Solana Wallet
         "currencyId":"6340313846e4f91b8abc519b", // USDC on Solana
         "sourceBlockchainEngine":"63b6b1200cfb4b3f6131f2b4" //Solana
      },
      {
         "walletId":"YOUR_SOLANA_WALLET_ID",
         "currencyId":"6340313846e4f91b8abc519b", // USDC on Solana
         "sourceBlockchainEngine":"63b6b1200cfb4b3f6131f2b2" //EVM
      }
   ],
}'

USDC on Base & Solana

EVM payment flows settle to USDC on Base; Solana flows settle to USDC on Solana. Add two recipients: one for Solana USDC (your Solana wallet) and one for Base USDC (your EVM wallet on Base). Use a distinct currencyId per chain from the currency list. pricingCurrency can match either USDC (here: Solana USDC).

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": "Swaps example (Base & Solana USDC)",
  "price": "1000000",
  "pricingCurrency": "6340313846e4f91b8abc519b",
  "features": { 
  	"canSwapTokens": true 
  },
  "recipients":[
      {
         "walletId":"YOUR_SOLANA_WALLET_ID",
         "currencyId":"6340313846e4f91b8abc519b", // USDC on Solana
         "sourceBlockchainEngine":"63b6b1200cfb4b3f6131f2b4" //Solana
      },
      {
         "walletId":"YOUR_EVM_WALLET_ID", // EVM Wallet
         "currencyId":"673751142b4993e64e14eef2", // USDC on Base
         "sourceBlockchainEngine":"63b6b1200cfb4b3f6131f2b2" //EVM
      }
   ],
}'

Full Request Body Options for Pay Link Creation

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 */
     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 */
     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 */
     hasRedirectQueryParams: boolean /* enable redirecting with query parameters */
     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 */
  	 customThemeEnabled?: boolean; /*enable custom theming on your paylink */
   };

   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;
   };
   
   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 */
   redirectQueryParams?: { queryParamType: string }[]; /* set redirect query param */
   
   airdropDetailsId?: string; /* set an ID for the airdrop details */

	customTheme?: {
    primaryColor: "#FF0000",  /* primary colour */
    neutralColor: "#00FF00", /* neutral colour */
    textColorOnButton: "WHITE", /* button text color: "WHITE" or "BLACK" */
    themeMode: "LIGHT", /* theme mode: "LIGHT" or "DARK" */
    backgroundColor?: "#0000FF" /* background color of the page*/
  }
}

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,
    "requireFixedCurrency": false,
    "canSwapTokens": false,
    "isHelioPlay": false,
    "isTransparentWallet": false,
    "nftDropEnabled": false,
    "showDiscountCode": false,
    "isEscrowed": false,
    "requireDiscordQuantityLimit": false,
    "requireAllowlist": 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": ""
}

API

WALLET

CURRENCY

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WITHDRAWALS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

Example Query

Token swaps

USDC on Solana only

USDC on Base & Solana

Full Request Body Options for Pay Link Creation

Response Body Example

​Example Query

​Token swaps

​USDC on Solana only

​USDC on Base & Solana

​Full Request Body Options for Pay Link Creation

​Response Body Example

Example Query

Token swaps

USDC on Solana only

USDC on Base & Solana

Full Request Body Options for Pay Link Creation

Response Body Example