> ## 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



## OpenAPI

````yaml post /submerchants
openapi: 3.0.0
info:
  title: Hub2 Service · Api
  description: |-
    This is the Hub2 api reference |
          Please check https://docs.hub2.io/ for the full documentation |
          Rate limits of endpoints are here : https://docs.hub2.io/en/details/limits.html.
  version: 2.177.0
  contact:
    name: Hub2
    url: https://www.hub2.io/
    email: contact@hub2.io
servers: []
security: []
tags:
  - name: Payments
    description: >-
      Best known as the PAY-IN API, it provides endpoints for merchants to
      perform Hub2 PAY-IN transactions.
  - name: Transfers
    description: >-
      Best known as the PAY-OUT API, it provides endpoints for merchants to
      perform Hub2 PAY-OUT transactions.
  - name: IRT
    description: International Remittance Transfers
  - name: Balance
    description: ''
  - name: Webhooks
    description: ''
  - name: Provisioning
    description: ''
  - name: Payment on Terminal
    description: ''
  - name: Receipt
    description: ''
  - name: Sms
    description: ''
  - name: Data
    description: ''
  - name: Compliance
    description: ''
  - name: Recipient
    description: ''
  - name: Delegation
    description: ''
  - name: Deposits
    description: ''
  - name: Payment Links
    description: ''
  - name: Subscription Links
    description: ''
  - name: Submerchants
    description: ''
  - name: Bill Payments
    description: ''
  - name: Subscriptions
    description: ''
  - name: Subscription Intents
    description: >-
      Enrolls a customer in card-on-file recurring debits and tracks how each
      enrollment ended.
  - name: Instant Payment
    description: >-
      Instant payment (PI SPI, BCEAO) resources, such as the aliases naming your
      accounts in the national directory.
paths:
  /submerchants:
    post:
      tags:
        - Submerchants
      summary: Create a submerchant
      operationId: SubmerchantsController_createSubmerchant
      parameters:
        - name: ApiKey
          in: header
          description: >-
            Your api key. To create a key, please get into our dashboard. If you
            don't have access to it, please reach the Support team.
          required: true
          schema:
            type: string
        - name: MerchantId
          in: header
          description: >-
            Your merchant ID. This information is available in our dashboard. If
            you don't have access to it, please reach the Support team.
          required: true
          schema:
            type: string
        - name: Environment
          in: header
          description: >-
            Allow you to choose between the sandbox mode to perform some tests
            or the live mode for real world transactions.
          required: true
          schema:
            type: string
            enum:
              - live
              - sandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubmerchantDto'
      responses:
        '201':
          description: Submerchant created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmerchantDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInvalidInputErrorAlias'
        '401':
          description: Wrong credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiUnauthorizedErrorAlias'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiNotFoundErrorAlias'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiInternalErrorAlias'
components:
  schemas:
    CreateSubmerchantDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the submerchant
          example: Submerchant Name
        description:
          type: string
          description: Description of the submerchant
          example: Submerchant description
        address:
          type: string
          description: Address of the submerchant
          example: 123 Main St
        zipcode:
          type: string
          description: Zipcode of the submerchant
          example: '12345'
        city:
          type: string
          description: City of the submerchant
          example: New York
        phoneNumber:
          type: string
          description: Phone number of the submerchant
          example: '+1234567890'
        legalInfo:
          description: Legal info of the submerchant
          allOf:
            - $ref: '#/components/schemas/SubmerchantLegalInfoDto'
      required:
        - name
        - description
    SubmerchantDto:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the merchant
          example: mch_1a2b3c
        createdAt:
          type: string
          description: Creation date of the merchant, ISO 8601
          example: '2026-08-13T09:00:00.000Z'
        name:
          type: string
          description: Name of the merchant
          example: Submerchant Name
        description:
          type: string
          description: Description of the merchant
        defaultCurrency:
          type: string
          description: Default currency of the merchant, ISO 4217
          example: XOF
        status:
          type: string
          description: Status of the merchant
          enum:
            - closed
            - live
            - sandbox
            - suspended
            - testing
            - initialized
        isActive:
          type: boolean
          description: Whether the merchant is active
        address:
          type: string
          description: Address of the merchant
        zipcode:
          type: string
          description: Zipcode of the merchant
        city:
          type: string
          description: City of the merchant
        phoneNumber:
          type: string
          description: Phone number of the merchant
        country:
          type: string
          description: Country of the merchant, ISO 3166-1 alpha-2
          example: CI
        isAggregator:
          type: boolean
          description: Whether the merchant is an aggregator
        members:
          description: Identifiers of the users that are members of the merchant
          type: array
          items:
            type: string
        preferences:
          description: Preferences of the merchant
          allOf:
            - $ref: '#/components/schemas/MerchantPreferencesDto'
        internalCode:
          type: string
          description: Internal code of the merchant
        activity:
          type: string
          description: Activity of the merchant
          enum:
            - compliance
            - inactive_30_days
            - inactive_90_days
            - low_performer
            - newcomer
            - top_performer
            - watch_list
        merchantGroupId:
          type: string
          description: Identifier of the group the merchant belongs to
        details:
          type: object
          description: Additional details of the merchant
        enabledProducts:
          description: Products enabled for the merchant
          type: array
          items:
            type: string
        legalInfo:
          description: Legal info of the submerchant
          allOf:
            - $ref: '#/components/schemas/SubmerchantLegalInfoDto'
      required:
        - id
        - createdAt
        - name
        - defaultCurrency
        - status
        - isActive
        - isAggregator
        - members
        - activity
    ApiInvalidInputErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP status.
          enum:
            - 400
          example: 400
        code:
          type: string
          description: >-
            The error code, e.g. `wrong_provider`, `invalid_url`,
            `invalid_sandbox_msisdn`, `credit_card_fees_not_supported`,
            `override_business_id`, `override_business_name`, `signature_error`,
            `merchant_not_found`,
            `payment_information.recipient_phone_plain_forbidden`,
            `transfer_information.recipient_phone_plain_forbidden`,
            `forbidden_special_chars`, `ci.mtn.description_too_big`. `Bad
            Request` for DTO validation failures and other uncoded 400s.
          example: wrong_provider
        message:
          description: >-
            What is wrong with the request. An array of messages when the
            payload fails DTO validation.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: >-
            Provider 'unknown_provider' does not exist for country 'CI' and
            method 'mobile_money'.
        request_id:
          type: string
          description: >-
            Identifier of the request, to quote when contacting the Support
            team.
      required:
        - status
        - code
        - message
        - request_id
    ApiUnauthorizedErrorAlias:
      type: object
      properties:
        status:
          type: number
          description: HTTP error code.
          example: 401
        error:
          description: HTTP error description.
          allOf:
            - $ref: '#/components/schemas/InternalApiUnauthorizedError'
      required:
        - status
        - error
    ApiNotFoundErrorAlias:
      type: object
      properties:
        httpStatus:
          type: number
          description: Http status
          enum:
            - 404
          example: 404
        message:
          type: string
          description: Detailed error message which describe what happened.
          example: X not found
        error:
          type: string
          description: Error message
          example: Not found
      required:
        - httpStatus
        - message
        - error
    ApiInternalErrorAlias:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: internal_error
        code:
          type: string
          description: The error code for this error.
          example:
            - internal_error
            - wrong_credentials
            - not_granted
            - live_mode_not_granted
        message:
          type: string
          description: The error message describing what happens to throw this error.
          example: An error occurred on our system. Please try again later.
      required:
        - type
        - code
        - message
    SubmerchantLegalInfoDto:
      type: object
      properties:
        legalName:
          type: string
          description: Legal name
        headOfficeAddress:
          type: string
          description: Legal head office address
        businessActivity:
          type: string
          description: Business activity
        managerName:
          type: string
          description: Manager name
        websiteURL:
          type: string
          description: Website URL
        isBetting:
          type: boolean
          description: Is betting
        isCrypto:
          type: boolean
          description: Is crypto
        isNGO:
          type: boolean
          description: Is NGO
    MerchantPreferencesDto:
      type: object
      properties: {}
    InternalApiUnauthorizedError:
      type: object
      properties:
        type:
          type: string
          description: The type of this error.
          example: authorization_error
        code:
          type: string
          description: The internal error code describing what happened.
          enum:
            - bad_payment_intent_token
            - wrong_credentials
          example: wrong_credentials
        message:
          type: string
          description: Detailed error message which describe what happened.
          example: L'ID marchand et/ou la clé d'API sont incorrects.
      required:
        - type
        - code
        - message

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.