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

# Create a submerchant

> This endpoint allows you to onboard a new submerchant and generate their unique ID for payment processing and transfers.

The Submerchant API allows you to create submerchant so that you can use their unique ID for transactions while ensuring compliance with regulatory requirements.

## Request Parameters

<ParamField body="name" type="string" required>
  Name of the submerchant (e.g., `Submerchant Name`)
</ParamField>

<ParamField body="description" type="string" optional>
  A description of the submerchant (e.g., `Submerchant description`).
  This field can be used to give information regarding submerchant activity.
</ParamField>

<ParamField body="address" type="string" optional>
  The street address of the submerchant (e.g., `RIVIERA BEVERLY HILLSt`).
</ParamField>

<ParamField body="zipcode" type="string" optional>
    The postal code or zip code of the submerchant (e.g., `00225`).
</ParamField>

<ParamField body="city" type="string" optional>
    The city of the submerchant (e.g., `ABIDJAN`).
</ParamField>

<ParamField body="phoneNumber" type="string" optional>
    The phone number of the submerchant (e.g., `+2250707070707`).
</ParamField>

## Response

**HTTP Status: 201 Created**

<ResponseField name="id" type="string">
  The unique ID for the submerchant (e.g., `wwIxF40ciS6NVQddoa5BQ`).
</ResponseField>

<ResponseField name="name" type="string">
    The name of the submerchant (e.g., `EM_TEST_01`).
</ResponseField>

<ResponseField name="description" type="string">
    A description of the submerchant (e.g., `Submerchant created for testing purposes`).
</ResponseField>

<ResponseField name="address" type="string">
    The street address of the submerchant.
</ResponseField>

<ResponseField name="zipcode" type="string">
    The postal code or zip code of the submerchant.
</ResponseField>

<ResponseField name="city" type="string">
    The city of the submerchant (e.g., `ABIDJAN`).
</ResponseField>

<ResponseField name="country" type="string">
    The two-letter ISO country code associated with the submerchant (e.g., `CI`).
  This value is inherited from the merchant.
</ResponseField>

<ResponseField name="currency" type="string">
    The currency code used by the submerchant (e.g., `XOF`).
  This value is inherited from the merchant.
</ResponseField>

<ResponseField name="phoneNumber" type="string">
    The phone number of the submerchant (e.g., `+2250707070707`).
</ResponseField>

<ResponseField name="isActive" type="boolean">
    A boolean flag indicating if the submerchant account is currently active (e.g., `true`).
</ResponseField>

<ResponseField name="status" type="string">
    The current operational status of the submerchant account (e.g., `live`).\
  Possible values: `live`, `sandbox`, `testing`, `suspended`, `archived`
</ResponseField>

<ResponseField name="activity" type="string">
    The defined activity level or performance tier of the submerchant (e.g., `top_performer`).
  Possible values: `new`, `top_performer `, `low_performer`, `watch_list`
</ResponseField>

<ResponseField name="preferences" type="object">
    An object containing specific configuration settings and preferences for the submerchant.
  This value is inherited from the merchant.
</ResponseField>

<ResponseField name="members" type="array">
    A list of users associated with the submerchant account (e.g., `[]`).
</ResponseField>

<ResponseField name="createdAt" type="string">
    The date and time the submerchant was created, in ISO 8601 format (e.g., `2025-11-28T18:21:44.687Z`).
</ResponseField>

<ResponseField name="updatedAt" type="string">
    The date and time the submerchant was last updated, in ISO 8601 format (e.g., `2025-11-28T18:21:44.750Z`).
</ResponseField>

<ResponseField name="legalInfo" type="null">
    Legal information associated with the submerchant (e.g., `null`).
</ResponseField>

<ResponseField name="internalCode" type="string">
    An internal code or reference number for the submerchant (e.g., `17C`).
</ResponseField>

<ResponseField name="policies" type="null">
    Applicable policies or terms for the submerchant (e.g., `null`).
</ResponseField>

<ResponseField name="isAggregator" type="boolean">
    A boolean flag indicating if the submerchant is configured as an aggregator (e.g., `false`).
</ResponseField>

<ResponseField name="merchantGroup" type="string">
    The ID of the merchant group to which the submerchant belongs (e.g., `tkExvG2obnQtXsrNMUw5d`).
</ResponseField>

<RequestExample>
  ```bash Submerchant Request theme={null}
  curl --location 'https://api.hub2.io/submerchants' \
  --header 'ApiKey: [REDACTED]' \
  --header 'MerchantId: [REDACTED]' \
  --header 'Environment: live' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "EM_TEST_01",
    "description": "Submerchant created for testing purposes",
    "address": "RIVIERA BEVERLY HILLS",
    "zipcode": "00225",
    "city": "ABIDJAN",
    "country": "CI",
    "currency": "XAF",
    "phoneNumber": "+2250707070707"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
         "id": "wwIxF40ciS6NVQddoa5BQ",
         "createdAt": "2025-11-27T18:37:55.033Z",
         "updatedAt": "2025-11-28T00:00:00.803Z",
         "name": "EM_TEST_01",
         "description": "Submerchant created for testing purposes",
         "country": "CI",
         "currency": "XOF",
         "members": [],
         "preferences": {
             "paymentWaveRestrictMsisdnEnabled": true
         },
         "address": "RIVIERA BEVERLY HILLS",
         "zipcode": "00225",
         "city": "ABIDJAN",
         "status": "suspended",
         "activity": "inactive_90_days",
         "isActive": true,
         "phoneNumber": null,
         "isAggregator": false,
         "policies": null,
         "legalInfo": null,
         "internalCode": "17B"
         "merchantGroup": "tkExvG2obnQtXsrNMUw5d" 
  }
  ```
</ResponseExample>