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 Type	Use Case	Credentials
Merchant API	Merchant accessing their own account	Merchant’s API Key + Secret
Partner API	Partner accessing merchant accounts	Platform API Key + Secret + Merchant ID

Authentication

Required Headers & Parameters

When making requests as a partner you must provide:

Parameter	Location	Description
apiKey	Query parameter	Your Platform API Key
Authorization	Header	Bearer token with your Platform API Secret
x-merchant-id	Header	The 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 Status	Error Message	Cause
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 Level	Permissions
READ_ONLY	Can only retrieve data (GET requests)
STANDARD	Can create and read pay links, transactions, etc.
ADMIN	Full access including sensitive operations

Best Practices

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

Getting Started

Request Platform API access - Contact the Helio team to become a platform partner
Receive credentials - You’ll receive a Platform API Key and Secret
Connect merchants - Merchants link their Helio accounts to your platform (store their Company IDs)
Make API calls - Use the x-merchant-id header to act on behalf of merchants

Ready to become a partner? Contact us at commerce@moonpay.com to request Platform API access.

API

WALLET

CURRENCY

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WITHDRAWALS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

Partner Account

How It Works

Authentication

Required Headers & Parameters

Example Request

Getting the Merchant ID

Supported Endpoints

Error Handling

Common Error Responses

Platform Key Without Merchant ID

Access Levels

Best Practices

Getting Started

​How It Works

​Authentication

​Required Headers & Parameters

​Example Request

​Getting the Merchant ID

​Supported Endpoints

​Error Handling

​Common Error Responses

​Platform Key Without Merchant ID

​Access Levels

​Best Practices

​Getting Started

How It Works

Authentication

Required Headers & Parameters

Example Request

Getting the Merchant ID

Supported Endpoints

Error Handling

Common Error Responses

Platform Key Without Merchant ID

Access Levels

Best Practices

Getting Started