> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Pay Link API creation request body and full options reference

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

```json theme={null}
{
  "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](/reference/currency/list), and see [here](https://docs.hel.io/reference/getting-started#1-retrieving-your-wallet-id) 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

```shell theme={null}
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": {}
}'
```

<Info>
  **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.
</Info>

## 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`](/reference/paylink/overview#full-request-body-options-for-pay-link-creation) set to `true`. For the full product explanation, see [No Code — Token Swaps](/docs/for-creators#token-swaps).

Resolve each `currencyId` from [Get Pay Link Currencies](/reference/currency/list) and each `walletId` from [Get wallets](/reference/wallet/list) or the dashboard.

### USDC on Solana only

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

```shell theme={null}
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).

```shell theme={null}
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.

```json theme={null}
{
   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

```json theme={null}
{
  "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": ""
}
```