🔗Create Pay Links via API

Create your Helio Pay Links programatically

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

Pre-requisites

In order to create Pay Links using Helio API, you need to complete the following steps.

1. Create Helio Account & get API keys

• Navigate to https://app.hel.io and login by using any of the login methods

• Navigate to the settings page and select the API tab

• Click on Enable checkbox, this will generate Public API Key and Secret API Key for you

• Save both securely since you won't be able to retrieve the Secret API Key again, however, you can always regenerate both (which will override the old one)

2. Prepare request payload

To create a Pay Link via API you will need to know which recipient wallet the paylink should send funds to, the payment currency (can be priced in fiat or crypto currency), and which recipient currency (or currencies) to accept payments in.

• Navigate to https://app.hel.io/settings and select Manage wallets tab

• Click on the 3 dots icon and select Copy Helio ID option, this is an internal Helio ID for your wallet (IMPORTANT: Helio ID is not the same as the Public Key)

• Using a browser or developer tool such as Postman or cURL, send a GET request to https://api.hel.io/v1/currency/all, this will return a real-time list of supported currencies. Select the currency you want "price" your Pay Link in, and which recipient currencies you want to accept payments in.

• For example here is a SOL currency object returned from https://api.hel.io/v1/currency/all

{
  id: '6340313846e4f91b8abc519b', // Copy this id
  name: 'USD Coin',
  decimals: 6,
  order: 1,
  mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  coinMarketCapId: 3408,
  symbol: 'USDC',
  symbolPrefix: '$',
  type: 'DIGITAL',
  iconUrl: 'USDC.svg',
  features: ['PAYMENT_PRICING', 'PAYMENT_RECIPIENT'],
  blockchain: {
    id: '6340313846e4f91b8abc515c',
    name: 'SOL',
    symbol: 'SOL',
    engine: { id: '63b6b1200cfb4b3f6131f2b4', type: 'SOL' },
  }
}

You should now have the following information:

API Key, API Token, Helio ID, Currency ID

Create the Pay Link using your API key

• 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.

• You can have multiple recipients (and the users will see a dropdown of which currencies to pay in)

• The recipient currency can be different to the pricing currency. For example you might want the pricing currency to be Euro, and always priced at 5 Euros (pricing currency), but accept USDC or USDT (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;

   features: {
     requireEmail?: boolean;
     requireDiscordUsername?: boolean;
     requireDiscordLogin?: boolean;
     requireFullName?: boolean;
     requireTwitterUsername?: boolean;
     requireCountry?: boolean;
     requireDeliveryAddress?: boolean;
     requirePhoneNumber?: boolean;
     requireProductDetails?: boolean;
     requireMaxTransactions?: boolean;
     requireNftGate?: boolean;
     requireDiscordAuth?: boolean;
     requireAccessCode?: boolean;
     requireFixedCurrency?: boolean;
     canSwapTokens?: boolean;
     isHelioPlay?: boolean;
     isTransparentWallet?: boolean;
     nftDropEnabled?: boolean;
     requireTradingViewUsername?: boolean;
     allowAffiliate?: boolean;
     enableCountdown?: boolean;
     isEventEnabled?: boolean;
     splitRevenue?: boolean;
     splitEqually?: boolean;
     canChangeQuantity?: boolean;
     requireQuantityLimits?: boolean;
     canChangePrice?: boolean;
     isHelioPlay?: boolean;
     isEscrowed?: boolean;
     showDiscountCode?: boolean;
     requireDiscordQuantityLimit?: boolean;
     requireAllowlist?: boolean;
     requireAirdrop?: boolean;
   };

   price?: string;

   pricingCurrency?: string;

   recipients?: {
      currencyId: string;
      walletId: string;
   }[];

   description?: string;

   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;

   notifyReceiverByEmail?: boolean = false;

   addDiscordRole?: boolean = false;

   discordRoleIds?: string[];

   disabled?: boolean;

   dynamic?: boolean;

   content?: {
     text?: string;
     mediaUrl?: string;
     mediaAttachmentId?: string;
   };

   maxTransactions?: number;

   product?: {
     name: string;
     description: string;
     type: 'TEXT' | 'SELECTOR';
   };

   nftCollectionAddress?: string;

   discordAuthDetails?: {
     serverId: string;
     roleId: string;
   }[];

   nftDrop?: {
     mintAddresses: string[]
   };

   accessCodeAuthProperties?: {
     accessCode: string;
   };

   fixedCurrency?: {
     currency: string;
     price: number;
   };

   tradingViewIndicators?: {
     id: string;
     url: string;
     name: string;
   }[];

   affiliateDetails?: {
     bps: number;
   };

   eventDetails?: {
     datetime: Date;
     location?: string;
   };

   countdownDetails?: {
     startDatetime: Date;
     endDatetime?: Date;
   };

   splitWallets?: {
     address: string;
     percent?: number;
     sharePercent?: number;
   }[];

   discountCodes?: {
     percent: number;
     token: string;
     prId?: string;
     id?: string;
     tokenType: 'CODE' | 'NFT_COLLECTION';
   }[];

   limitSaleType?: 'TRANSACTION' | 'DISCORD_ID';

   minQuantity?: number;

   maxQuantity?: number;

   helioPlayProperties?: {
     durationSec?: number;
     previewAttachmentId?: string;
     media: {
       type: 'VIDEO';
       hosted: boolean;
     };
   };
}

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
  },
  "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"
      }
    }
  }
}