Skip to content
API Reference/
/
Create signup session

Helix-Pay API (1.0.0)

API documentation for the Helix-Pay API

Download OpenAPI description
external.gen.json
external.gen.yaml
Languages
Servers
Mock server
https://docs.helix-pay.net/_mock/apis/external.gen/
Production server
https://api.helix-pay.net/v1/

Payments

Operations related to payments

Operations

Consumers

Operations related to consumers. Consumers are mostly used in marketplace-type applications where they can deposit money in their account to pay for other goods or services or payout to their bank accounts.

Operations

Wallets

Operations related to wallets. Wallets are used to store funds for consumers.

Operations

Banks

Operations related to bank accounts. Bank accounts are used to withdraw funds from wallets.

Operations

Payouts

Operations related to payouts. Payouts are used to withdraw funds from wallets to bank accounts.

Operations

Integrations

Operations related to integrations. Integrations are used to connect Helix Pay with external systems (e.g. WIX).

Operations

Customers

Operations related to customers. Customers are the end-users who make payments. Not to be confused with consumers.

Operations

Balances

Operations related to account balances.

Operations

Sub-Merchants

Operations related to sub-merchants management. Allows parent merchants to manage their sub-merchants and create payments on their behalf, while also viewing volume analytics and current balances.

Operations

List sub-merchants

Request

Get a list of all sub-merchants associated with your parent merchant account.

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(SubMerchantSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

List signup sessions

Request

Get all signup sessions created by your parent merchant

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(SignupSessionSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Create signup session

Request

Create a new signup session for a sub-merchant

Security
ApiKeyAuth
Bodyapplication/jsonrequired
merchant_namestring
user_emailstring
merchant_typestring
Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring
country_codestring(iso-alpha-2)
expires_atstring

The expiration date of the session

Example: "2025-01-16T00:00:00.000Z"
curl -i -X POST \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "merchant_name": "string",
    "user_email": "string",
    "merchant_type": "BUSINESS",
    "merchant_category": "string",
    "country_code": "string",
    "expires_at": "2025-01-16T00:00:00.000Z"
  }'

Responses

Signup session created

Bodyapplication/json
idstring

The unique identifier for the signup session

Example: "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
user_emailstring

The email address for the signup session

Example: "newmerchant@example.com"
merchant_namestring

The name of the merchant to be created

Example: "New Store"
statusstring

The status of the signup session

Enum"PENDING""COMPLETED""EXPIRED""CANCELLED"
Example: "PENDING"
merchant_typestring

The type of the merchant, if provided during creation

Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring

The merchant category, if provided during creation

Example: "RETAIL"
country_codestring

The country code for the merchant, if provided during creation

Example: "US"
expires_atstring(date-time)

The timestamp when the signup session expires

created_atstring(date-time)

The timestamp when the signup session was created

Response
application/json
{
  "id": "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "user_email": "newmerchant@example.com",
  "merchant_name": "New Store",
  "status": "PENDING",
  "merchant_type": "BUSINESS",
  "merchant_category": "RETAIL",
  "country_code": "US",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Get signup session

Request

Retrieve details of a specific signup session

Security
ApiKeyAuth
Path
sessionIdstringrequired

The unique identifier for the signup session

Example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions/mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
idstring

The unique identifier for the signup session

Example: "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
user_emailstring

The email address for the signup session

Example: "newmerchant@example.com"
merchant_namestring

The name of the merchant to be created

Example: "New Store"
statusstring

The status of the signup session

Enum"PENDING""COMPLETED""EXPIRED""CANCELLED"
Example: "PENDING"
merchant_typestring

The type of the merchant, if provided during creation

Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring

The merchant category, if provided during creation

Example: "RETAIL"
country_codestring

The country code for the merchant, if provided during creation

Example: "US"
expires_atstring(date-time)

The timestamp when the signup session expires

created_atstring(date-time)

The timestamp when the signup session was created

Response
application/json
{
  "id": "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "user_email": "newmerchant@example.com",
  "merchant_name": "New Store",
  "status": "PENDING",
  "merchant_type": "BUSINESS",
  "merchant_category": "RETAIL",
  "country_code": "US",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Update signup session

Request

Update an existing signup session

Security
ApiKeyAuth
Path
sessionIdstringrequired

The unique identifier for the signup session

Example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Bodyapplication/jsonrequired
merchant_namestring
user_emailstring
merchant_typestring
Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring
country_codestring(iso-alpha-2)
expires_atstring

The expiration date of the session

Example: "2025-01-16T00:00:00.000Z"
curl -i -X PATCH \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions/mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "merchant_name": "string",
    "user_email": "string",
    "merchant_type": "BUSINESS",
    "merchant_category": "string",
    "country_code": "string",
    "expires_at": "2025-01-16T00:00:00.000Z"
  }'

Responses

Signup session updated

Bodyapplication/json
idstring

The unique identifier for the signup session

Example: "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
user_emailstring

The email address for the signup session

Example: "newmerchant@example.com"
merchant_namestring

The name of the merchant to be created

Example: "New Store"
statusstring

The status of the signup session

Enum"PENDING""COMPLETED""EXPIRED""CANCELLED"
Example: "PENDING"
merchant_typestring

The type of the merchant, if provided during creation

Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring

The merchant category, if provided during creation

Example: "RETAIL"
country_codestring

The country code for the merchant, if provided during creation

Example: "US"
expires_atstring(date-time)

The timestamp when the signup session expires

created_atstring(date-time)

The timestamp when the signup session was created

Response
application/json
{
  "id": "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "user_email": "newmerchant@example.com",
  "merchant_name": "New Store",
  "status": "PENDING",
  "merchant_type": "BUSINESS",
  "merchant_category": "RETAIL",
  "country_code": "US",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Delete signup session

Request

Delete a signup session. This only works if the session is in CREATED status. Already completed, in progress, or expired sessions cannot be deleted.

Security
ApiKeyAuth
Path
sessionIdstringrequired

The unique identifier for the signup session

Example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
curl -i -X DELETE \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions/mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Signup session deleted

Reactivate signup session

Request

Reactivate an expired or cancelled signup session. This extends an expired session by 3 days from the time of reactivation.

Security
ApiKeyAuth
Path
sessionIdstringrequired

The unique identifier for the signup session

Example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Bodyapplication/jsonrequired
expires_in_hoursinteger[ 1 .. 168 ]

Number of hours until the session expires

Default 168
Example: 168
curl -i -X POST \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/signup-sessions/mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/reactivate \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "expires_in_hours": 168
  }'

Responses

Signup session reactivated

Bodyapplication/json
idstring

The unique identifier for the signup session

Example: "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
user_emailstring

The email address for the signup session

Example: "newmerchant@example.com"
merchant_namestring

The name of the merchant to be created

Example: "New Store"
statusstring

The status of the signup session

Enum"PENDING""COMPLETED""EXPIRED""CANCELLED"
Example: "PENDING"
merchant_typestring

The type of the merchant, if provided during creation

Enum"BUSINESS""PARTNERSHIP""ORGANIZATION""SOLETRADER"
Example: "BUSINESS"
merchant_categorystring

The merchant category, if provided during creation

Example: "RETAIL"
country_codestring

The country code for the merchant, if provided during creation

Example: "US"
expires_atstring(date-time)

The timestamp when the signup session expires

created_atstring(date-time)

The timestamp when the signup session was created

Response
application/json
{
  "id": "mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9",
  "user_email": "newmerchant@example.com",
  "merchant_name": "New Store",
  "status": "PENDING",
  "merchant_type": "BUSINESS",
  "merchant_category": "RETAIL",
  "country_code": "US",
  "expires_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Get sub-merchant balance

Request

Get the current balance for a specific sub-merchant

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Query
currencystring

The currency code to filter the balance (e.g. USD, EUR). If not provided, returns balance in all currencies.

Example: currency=USD
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/balance?currency=USD' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
balanceobject

A map of currency codes to their respective balances

Example: {"USD":1000,"EUR":500}
currencystring

The currency code of the balance (if a specific currency was requested)

Example: "USD"
Response
application/json
{
  "balance": {
    "USD": 1000,
    "EUR": 500
  },
  "currency": "USD"
}

Get sub-merchant payments

Request

Retrieve payments for a specific sub-merchant

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Query
limitinteger[ 1 .. 100 ]

The maximum number of payments to return

Default 10
offsetinteger>= 0

The number of payments to skip

Default 0
statusstring

Filter payments by status

Enum"pending""completed""failed"
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/payments?limit=10&offset=0&status=pending' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(PaymentSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Get a sub-merchant's payouts.

Request

Retrieve the payouts for a specific sub-merchant.

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Query
limitinteger[ 1 .. 100 ]

The maximum number of payouts to return

Default 10
offsetinteger>= 0

The number of payouts to skip

Default 0
statusstring

Filter payouts by status

Enum"pending""completed""failed"
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/payouts?limit=10&offset=0&status=pending' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(MerchantPayoutSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Get the details of a specific sub-merchant payout.

Request

Retrieve the details of a specific payout for a sub-merchant.

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
payoutIdstringrequired

The unique identifier for the payout

Example: pyo_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/payouts/pyo_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
idstring

The unique identifier for the payout

amountnumber

The amount of the payout

currencystring

The currency of the payout

statusstring

The status of the payout

created_atstring(date-time)

The timestamp when the payout was created

updated_atstring(date-time)

The timestamp when the payout was last updated

Response
application/json
{
  "id": "string",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Get transactions for a specific sub-merchant payout.

Request

Retrieve the transactions associated with a specific payout for a sub-merchant. Transactions can be of type PAYMENT or REFUND.

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
Query
limitinteger[ 1 .. 100 ]

The maximum number of transactions to return

Default 10
offsetinteger>= 0

The number of transactions to skip

Default 0
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/payouts/{payoutId}/transactions?limit=10&offset=0' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
dataArray of objects(PayoutTransactionSchema)
metadataobject
Response
application/json
{
  "data": [
    { … }
  ],
  "metadata": {
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Get sub-merchant API key

Request

Retrieve the API key information for a sub-merchant. This is a temporary endpoint and will be deprecated in the future. Useful to create payments on behalf of your sub-merchants.

Security
ApiKeyAuth
Path
merchantIdstringrequired

The unique identifier for the sub-merchant

Example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/merchants/mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9/api-key \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
keystring

The API key value

Example: "hpk_test_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
Response
application/json
{
  "key": "hpk_test_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9"
}

Get merchant volumes

Request

Get gross and net volumes for all your sub-merchants for a specified date and currency. If no date is provided, it defaults to the previous full day.

Security
ApiKeyAuth
Query
currencystring

Filter by currency code

Example: currency=EUR
datestring(date)

The date to get volumes for (YYYY-MM-DD). Defaults to the previous full day if not provided.

Example: date=2025-10-01
curl -i -X GET \
  'https://docs.helix-pay.net/_mock/apis/external.gen/merchants/volumes?currency=EUR&date=2025-10-01' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
grossnumber

The gross volume amount

Example: 10000
netnumber

The net volume amount

Example: 9500
Response
application/json
{
  "gross": 10000,
  "net": 9500
}

Health check endpoint

Request

A simple endpoint to check the health of the API

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.helix-pay.net/_mock/apis/external.gen/health \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
messagestringrequired
Response
application/json
{
  "message": "string"
}
Copyright © Helix-Pay LTD. No rights reserved.