Skip to main content
Partner API Access allows platform partners to make API calls on behalf of their connected merchants. This is useful for platforms that integrate Helio and need to manage payments, pay links, and transactions for multiple merchant accounts. Partner API Access is available for approved platform partners only. Contact the Helio team to request Platform API credentials.

​
How It Works

Instead of each merchant generating their own API keys, platform partners receive a single set of Platform API credentials that can be used to access any merchant account linked to their platform.
Authentication TypeUse CaseCredentials
Merchant APIMerchant accessing their own accountMerchant’s API Key + Secret
Partner APIPartner accessing merchant accountsPlatform API Key + Secret + Merchant ID

​
Authentication

​
Required Headers & Parameters

When making requests as a partner you must provide:
ParameterLocationDescription
apiKeyQuery parameterYour Platform API Key
AuthorizationHeaderBearer token with your Platform API Secret
x-merchant-idHeaderThe Helio Company ID of the merchant you’re acting on behalf of

​
Example Request

curl --request POST \
  --url "https://api.hel.io/v1/paylink/create/api-key?apiKey=YOUR_PLATFORM_API_KEY" \
  --header "Authorization: Bearer YOUR_PLATFORM_API_SECRET" \
  --header "Content-Type: application/json" \
  --header "x-merchant-id: MERCHANT_COMPANY_ID" \
  --data '{
    "name": "Example Pay Link",
    "price": "1000000",
    "pricingCurrency": "6340313846e4f91b8abc519b",
    "template": "OTHER",
    "features": {
      "canChangeQuantity": false,
      "canChangePrice": false
    },
    "recipients": [
      {
        "walletId": "MERCHANT_WALLET_ID",
        "currencyId": "6340313846e4f91b8abc519b"
      }
    ]
  }'

​
Getting the Merchant ID

The x-merchant-id header requires the merchant’s Company ID. This is the internal identifier for the merchant’s account in Helio. You can find the Helio company ID upon creation of a merchant account using the Create a Merchant Account endpoint. This is the internal identifier for the merchant’s account. As a platform partner, you should store this ID when merchants connect their accounts to your platform.

​
Supported Endpoints

Partner API Access works with all merchant-facing API endpoints, including:
  • Pay Links - Create, update, disable pay links
  • Transactions - Retrieve transaction history
  • Charges - Create and manage charges
  • Deposits - Create deposits and manage customers
  • Subscriptions - View subscription details
  • Webhooks - Manage webhook configurations

​
Error Handling

​
Common Error Responses

HTTP StatusError MessageCause
401”Please provide platform apiKey and bearer token”Missing apiKey query parameter or Authorization header
401”Invalid platform API key”Platform API key not found or disabled
401”Invalid platform API secret”Bearer token doesn’t match the API key
401”Merchant not found”Invalid x-merchant-id or merchant doesn’t exist
401”Not authorized to access this merchant”Merchant is not linked to your platform

​
Platform Key Without Merchant ID

If you accidentally use a Platform API key without the x-merchant-id header, you’ll recieve: 
{
  "statusCode": 401,
  "message": "Platform API key detected. Please include 'x-merchant-id' header with the merchant ID"
}

​
Access Levels

Platform API keys have an associated access level that determines which operations are permitted. The access level is configured when the Platform API key is issued.
Access LevelPermissions
READ_ONLYCan only retrieve data (GET requests)
STANDARDCan create and read pay links, transactions, etc.
ADMINFull access including sensitive operations

​
Best Practices

  1. Store Platform credentials securely - Never expose your Platform API secret in client-side code
  2. Validate merchant IDs - Ensure the merchant ID is valid before making API calls
  3. Handle errors gracefully - Implement proper error handling for authorization failures
  4. Use HTTPS only - All API requests must use HTTPS

​
Getting Started

  1. Request Platform API access - Contact the Helio team to become a platform partner
  2. Receive credentials - You’ll receive a Platform API Key and Secret
  3. Connect merchants - Merchants link their Helio accounts to your platform (store their Company IDs)
  4. Make API calls - Use the x-merchant-id header to act on behalf of merchants
Ready to become a partner? Contact us at partners@hel.io to request Platform API access.