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

# Create Merchant

> Create a new merchant with settlement and company details.

## Overview

The Create Merchant endpoint allows Payment Aggregators (PSPs) to programmatically onboard sub-merchants. It creates a new merchant account with company details, settlement bank information, and contact details.

After creation, the sub-merchant status depends on the environment:

* **Production**: Status is set to `PENDING` (requires approval)
* **Non-production**: Status is set to `APPROVED` (auto-approved for testing)

## Request Parameters

### Required Parameters

* `company_details`: Company registration, business information, and contact details
* `settlement_details`: Bank account details for settlements

### Parameter Definitions

#### Top-level

| Name                | Type   | Required | Description                             | Constraints            |
| ------------------- | ------ | -------- | --------------------------------------- | ---------------------- |
| company\_details    | object | Yes      | Company, business, and contact details. | See Company Details    |
| settlement\_details | object | Yes      | Bank account details for settlements.   | See Settlement Details |

#### Company Details

| Name                                     | Type    | Required      | Description                                       | Constraints                                                                                                                                                                                                                                |
| ---------------------------------------- | ------- | ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| email                                    | string  | Yes           | Contact email for the sub-merchant.               | RFC 5322 email format                                                                                                                                                                                                                      |
| phone\_number                            | string  | Yes           | Contact phone number with country code.           | E.164 format (e.g., `+919876543210`)                                                                                                                                                                                                       |
| legal\_name                              | string  | Yes           | Legal name of the company.                        | Max 255 chars                                                                                                                                                                                                                              |
| brand\_name                              | string  | Yes           | Brand/trade name.                                 | Max 255 chars                                                                                                                                                                                                                              |
| registration\_number                     | string  | Yes           | Company registration number.                      | Alphanumeric with dashes                                                                                                                                                                                                                   |
| international\_org\_type                 | string  | Yes           | Type of organization.                             | Enum: `Private Limited Company`, `Public Limited Company`, `Limited Liability Company`, `Joint Stock Company`, `Free Zone Company / Entity`, `Partnership / LLP`, `Sole Proprietorship`, `Other`                                           |
| tax\_id                                  | string  | Yes           | Tax identification number.                        | Alphanumeric with dashes                                                                                                                                                                                                                   |
| website                                  | string  | Yes           | Company website URL.                              | Must include `https://` prefix                                                                                                                                                                                                             |
| monthly\_avg\_transaction\_volume        | string  | Yes           | Expected monthly transaction volume.              | Enum: `LESS_THAN_5_K`, `BETWEEN_5_K_AND_20_K`, `BETWEEN_20_K_AND_50_K`, `BETWEEN_50_K_AND_100_K`, `BETWEEN_100_K_AND_250_K`, `BETWEEN_250_K_AND_500_K`, `ABOVE_500_K`                                                                      |
| business\_category                       | string  | Yes           | Business category (comma-separated for multiple). | Enum: `E-commerce (physical goods & cross-border shipping)`, `Digital goods / software / downloads`, `SaaS / subscriptions / recurring billing`, `Services (delivered cross-border)`, `Marketplace / platform (multiple sellers)`, `Other` |
| business\_category\_other                | string  | Conditionally | Description when category includes "Other".       | Required if `business_category` includes `Other`                                                                                                                                                                                           |
| business\_mode                           | string  | Yes           | Mode of business.                                 | Enum: `b2b`, `b2c`, `marketplace`                                                                                                                                                                                                          |
| description\_of\_products\_and\_services | string  | Yes           | Detailed description of products/services.        | Max 1024 chars                                                                                                                                                                                                                             |
| mcc                                      | string  | No            | Merchant Category Codes.                          | Comma-separated 4-digit codes (e.g., `5411,5812`)                                                                                                                                                                                          |
| hs\_codes                                | array   | No            | HS codes for goods traded.                        | Array of HS code strings                                                                                                                                                                                                                   |
| agreement\_details                       | string  | No            | Agreement details with the merchant.              | Max 1024 chars                                                                                                                                                                                                                             |
| registered\_address                      | string  | Yes           | Registered office address.                        | Max 255 chars                                                                                                                                                                                                                              |
| registered\_city                         | string  | Yes           | Registered office city.                           | Max 255 chars                                                                                                                                                                                                                              |
| registered\_state                        | string  | Yes           | Registered office state/province.                 | Max 255 chars                                                                                                                                                                                                                              |
| registered\_country                      | string  | Yes           | Registered office country.                        | Full country name (e.g., `India`, `United States`)                                                                                                                                                                                         |
| registered\_pincode                      | string  | Yes           | Registered office postal code.                    | Max 20 chars                                                                                                                                                                                                                               |
| same\_as\_registered\_address            | boolean | Yes           | Whether communication address matches registered. | `true` or `false`                                                                                                                                                                                                                          |
| communication\_address                   | string  | Conditionally | Communication address.                            | Required if `same_as_registered_address` is `false`                                                                                                                                                                                        |
| communication\_city                      | string  | Conditionally | Communication city.                               | Required if `same_as_registered_address` is `false`                                                                                                                                                                                        |
| communication\_state                     | string  | Conditionally | Communication state.                              | Required if `same_as_registered_address` is `false`                                                                                                                                                                                        |
| communication\_country                   | string  | Conditionally | Communication country.                            | Required if `same_as_registered_address` is `false`                                                                                                                                                                                        |
| communication\_pincode                   | string  | Conditionally | Communication postal code.                        | Required if `same_as_registered_address` is `false`                                                                                                                                                                                        |

Notes:

* When `same_as_registered_address` is `true`, communication address fields are auto-populated from registered address.
* Multiple business categories can be comma-separated (e.g., `"E-commerce (physical goods & cross-border shipping),SaaS / subscriptions / recurring billing"`).

#### Settlement Details

| Name                  | Type   | Required | Description               | Constraints                                        |
| --------------------- | ------ | -------- | ------------------------- | -------------------------------------------------- |
| bank\_account\_number | string | Yes      | Bank account number.      | Alphanumeric                                       |
| bank\_account\_name   | string | Yes      | Name on the bank account. | Max 255 chars                                      |
| bank\_swift\_code     | string | Yes      | SWIFT/BIC code.           | Standard SWIFT format                              |
| bank\_name            | string | Yes      | Name of the bank.         | Max 255 chars                                      |
| bank\_branch\_name    | string | Yes      | Branch name.              | Max 255 chars                                      |
| bank\_address         | string | Yes      | Bank branch address.      | Max 255 chars                                      |
| bank\_city            | string | Yes      | Bank city.                | Max 255 chars                                      |
| bank\_state           | string | Yes      | Bank state/province.      | Max 255 chars                                      |
| bank\_country         | string | Yes      | Bank country.             | Full country name (e.g., `India`, `United States`) |
| bank\_pincode         | string | Yes      | Bank postal code.         | Max 20 chars                                       |
| routing\_number       | string | Yes      | Routing/IFSC number.      | Alphanumeric                                       |

## Examples

<CodeGroup>
  ```json Software Company (B2B) theme={null}
  {
    "company_details": {
      "email": "contact@acmetech.com",
      "phone_number": "+919876543210",
      "legal_name": "Acme Technologies Pvt Ltd",
      "brand_name": "AcmeTech",
      "registration_number": "U72200MH2020PTC123456",
      "international_org_type": "Private Limited Company",
      "tax_id": "AACCA1234A",
      "website": "https://acmetech.com",
      "monthly_avg_transaction_volume": "BETWEEN_20_K_AND_50_K",
      "business_category": "Digital goods / software / downloads",
      "business_mode": "b2b",
      "description_of_products_and_services": "Cloud-based enterprise resource planning software for mid-market companies",
      "mcc": "5734",
      "registered_address": "Tower A, Techpark, Whitefield",
      "registered_city": "Bangalore",
      "registered_state": "Karnataka",
      "registered_country": "India",
      "registered_pincode": "560066",
      "same_as_registered_address": true,
      "communication_address": "Tower A, Techpark, Whitefield",
      "communication_city": "Bangalore",
      "communication_state": "Karnataka",
      "communication_country": "India",
      "communication_pincode": "560066"
    },
    "settlement_details": {
      "bank_account_number": "1234567890123456",
      "bank_account_name": "Acme Technologies Pvt Ltd",
      "bank_swift_code": "HDFCINBB",
      "bank_name": "HDFC Bank",
      "bank_branch_name": "Whitefield Branch",
      "bank_address": "100 Feet Road, Whitefield",
      "bank_city": "Bangalore",
      "bank_state": "Karnataka",
      "bank_country": "India",
      "bank_pincode": "560066",
      "routing_number": "HDFC0001234"
    }
  }
  ```

  ```json E-commerce (B2C, US) theme={null}
  {
    "company_details": {
      "email": "ops@globalshop.com",
      "phone_number": "+14155551234",
      "legal_name": "GlobalShop Inc",
      "brand_name": "GlobalShop",
      "registration_number": "US-CORP-2024-GS789456",
      "international_org_type": "Limited Liability Company",
      "tax_id": "94-8765432",
      "website": "https://globalshop.com",
      "monthly_avg_transaction_volume": "BETWEEN_100_K_AND_250_K",
      "business_category": "E-commerce (physical goods & cross-border shipping),SaaS / subscriptions / recurring billing",
      "business_mode": "b2c",
      "description_of_products_and_services": "Multi-category e-commerce platform selling electronics, apparel, and home goods with subscription box services",
      "mcc": "5411,5812",
      "hs_codes": ["85234910", "84715000"],
      "agreement_details": "Master Service Agreement dated 2024-03-15",
      "registered_address": "Suite 1200, 101 California Street",
      "registered_city": "San Francisco",
      "registered_state": "CA",
      "registered_country": "United States",
      "registered_pincode": "94111",
      "same_as_registered_address": false,
      "communication_address": "1455 Market Street, Suite 1600",
      "communication_city": "San Francisco",
      "communication_state": "CA",
      "communication_country": "United States",
      "communication_pincode": "94103"
    },
    "settlement_details": {
      "bank_account_number": "6789123450987654",
      "bank_account_name": "GlobalShop Inc",
      "bank_swift_code": "CHASINUS33XXX",
      "bank_name": "JPMorgan Chase Bank",
      "bank_branch_name": "Financial District Branch",
      "bank_address": "270 Park Avenue, New York",
      "bank_city": "New York",
      "bank_state": "NY",
      "bank_country": "United States",
      "bank_pincode": "10017",
      "routing_number": "021000021"
    }
  }
  ```

  ```json Other Category (UAE) theme={null}
  {
    "company_details": {
      "email": "finance@innovate.io",
      "phone_number": "+971501234567",
      "legal_name": "Innovate FZE",
      "brand_name": "Innovate",
      "registration_number": "FZ-2024-INV-001",
      "international_org_type": "Free Zone Company / Entity",
      "tax_id": "TRN100123456",
      "website": "https://innovate.io",
      "monthly_avg_transaction_volume": "BETWEEN_50_K_AND_100_K",
      "business_category": "Other",
      "business_category_other": "AI-powered supply chain optimization and logistics analytics platform",
      "business_mode": "b2b",
      "description_of_products_and_services": "AI-driven logistics optimization platform that helps enterprises reduce shipping costs and delivery times",
      "mcc": "7372",
      "registered_address": "Office 1205, Business Bay Tower",
      "registered_city": "Dubai",
      "registered_state": "Dubai",
      "registered_country": "United Arab Emirates",
      "registered_pincode": "00000",
      "same_as_registered_address": true,
      "communication_address": "Office 1205, Business Bay Tower",
      "communication_city": "Dubai",
      "communication_state": "Dubai",
      "communication_country": "United Arab Emirates",
      "communication_pincode": "00000"
    },
    "settlement_details": {
      "bank_account_number": "AE070331234567890123456",
      "bank_account_name": "Innovate FZE",
      "bank_swift_code": "ABORAEADXXX",
      "bank_name": "Arab Bank",
      "bank_branch_name": "Dubai Main Branch",
      "bank_address": "Sheikh Zayed Road, Dubai",
      "bank_city": "Dubai",
      "bank_state": "Dubai",
      "bank_country": "United Arab Emirates",
      "bank_pincode": "00000",
      "routing_number": "ABOR0000001"
    }
  }
  ```
</CodeGroup>

## Response Examples

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "message": "Sub-merchant created successfully",
    "data": {
      "id": "6182929449",
      "company_details": {
        "legal_name": "Acme Technologies Pvt Ltd",
        "brand_name": "AcmeTech",
        "email": "contact@acmetech.com",
        "phone_number": "+919876543210",
        "registration_number": "U72200MH2020PTC123456",
        "international_org_type": "Private Limited Company",
        "tax_id": "AACCA1234A",
        "website": "https://acmetech.com",
        "monthly_avg_transaction_volume": "BETWEEN_20_K_AND_50_K",
        "communication_address": "Tower A, Techpark, Whitefield",
        "communication_city": "Bangalore",
        "communication_state": "Karnataka",
        "communication_country": "India",
        "communication_pincode": "560066",
        "same_as_registered_address": true,
        "registered_address": "Tower A, Techpark, Whitefield",
        "registered_city": "Bangalore",
        "registered_state": "Karnataka",
        "registered_country": "India",
        "registered_pincode": "560066",
        "business_category": "Digital goods / software / downloads",
        "business_category_other": null,
        "business_mode": "b2b",
        "hs_codes": [],
        "description_of_products_and_services": "Cloud-based enterprise resource planning software for mid-market companies",
        "agreement_details": null
      },
      "settlement_details": {
        "bank_account_number": "1234567890123456",
        "bank_account_name": "Acme Technologies Pvt Ltd",
        "bank_swift_code": "HDFCINBB",
        "bank_name": "HDFC Bank",
        "bank_branch_name": "Whitefield Branch",
        "bank_address": "100 Feet Road, Whitefield",
        "bank_city": "Bangalore",
        "bank_state": "Karnataka",
        "bank_country": "India",
        "bank_pincode": "560066",
        "routing_number": "HDFC0001234",
        "settlement_currency": "USD"
      },
      "kyc_status": "PENDING",
      "created_at": "2026-04-28T06:30:00.000000Z",
      "last_updated_at": "2026-04-28T06:30:00.000000Z"
    }
  }
  ```

  ```json Validation Error theme={null}
  {
    "success": false,
    "error": {
      "code": "ERR_MERCHANT_001",
      "message": "Validation error",
      "details": {
        "company_details": {
          "monthly_avg_transaction_volume": "\"500\" is not a valid choice.",
          "business_mode": "\"invalid\" is not a valid choice.",
          "registered_country": "Invalid country name"
        }
      }
    }
  }
  ```
</CodeGroup>

## Error Codes

| Code               | Message          | Description                                                        |
| ------------------ | ---------------- | ------------------------------------------------------------------ |
| ERR\_MERCHANT\_001 | Validation error | Request validation failed — check `details` for field-level errors |

## Implementation Notes

### Merchant Status Flow

* **PENDING** → Created, awaiting approval
* **IN\_REVIEW** → Under compliance review
* **APPROVED** → Active, can process payments
* **CHANGES\_REQUESTED** → Additional information required
* **REJECTED** → Application rejected

### Country Names

Country fields (`registered_country`, `communication_country`, `bank_country`) must use the full country name (e.g., `"India"`, `"United States"`, `"United Arab Emirates"`).

### Phone Number Format

Phone numbers must include the country code in E.164 format (e.g., `+919876543210`, `+14155551234`).

### Business Category

Multiple categories can be comma-separated. When `"Other"` is included, `business_category_other` must provide a description.


## OpenAPI

````yaml POST /partners/merchants/
openapi: 3.0.0
info:
  title: Eximpe Payment Gateway API
  description: >-
    API for payment processing and order management through Eximpe payment
    gateway. This specification includes v1, v2, and v3 API versions.
  license:
    name: Proprietary
  version: 2.0.0
servers:
  - url: https://api-pacb-uat.eximpe.com
    description: Payment Gateway Sandbox URL
security:
  - clientAuth: []
    clientSecretAuth: []
    apiVersionHeader: []
tags:
  - name: Card Tokens
  - name: Merchants
  - name: Orders
  - name: Payment Links
  - name: Payments
  - name: Refunds
  - name: Settlements
  - name: Subscriptions
paths:
  /partners/merchants/:
    post:
      tags:
        - Merchants
      summary: Create Merchant
      description: Create a new merchant with settlement and company details.
      operationId: v1_post_partners_merchants_
      requestBody:
        description: Merchant details to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1_CreateMerchantRequest'
            example:
              settlement_details:
                bank_account_number: '6789123450987654'
                bank_account_name: InnovateTech Solutions Private Limited
                bank_swift_code: CHASINUS33XXX
                bank_name: JPMorgan Chase Bank
                bank_branch_name: Financial District Branch
                bank_address: 270 Park Avenue, New York
                bank_city: New York
                bank_state: NY
                bank_country: United States
                bank_pincode: '10017'
                routing_number: '021000021'
              company_details:
                legal_name: InnovateTech Solutions Private Limited
                brand_name: InnovateTech
                registration_number: US-CORP-2024-IT789456
                international_org_type: Private Limited Company
                tax_id: 94-8765432
                website: https://www.innovatetech.com
                monthly_avg_transaction_volume: BETWEEN_20_K_AND_50_K
                communication_address: Suite 1200, 101 California Street
                communication_city: San Francisco
                communication_state: CA
                communication_country: United States
                communication_pincode: '94111'
                same_as_registered_address: false
                registered_address: 1455 Market Street, Suite 1600
                registered_city: San Francisco
                registered_state: CA
                registered_country: United States
                registered_pincode: '94103'
                business_category: E-commerce (physical goods & cross-border shipping)
                business_mode: b2b
                hs_codes:
                  - '85234910'
                  - '84715000'
                description_of_products_and_services: >-
                  InnovateTech provides cutting-edge cloud computing solutions,
                  artificial intelligence platforms, and enterprise software
                  systems. We specialize in machine learning algorithms, data
                  analytics, and scalable cloud infrastructure for Fortune 500
                  companies.
                agreement_details: Master Service Agreement for Cloud Solutions dated 2024-03-15
                email: merchant@example.com
                phone_number: '+919876543210'
        required: true
      responses:
        '201':
          description: Merchant created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_CreateMerchantResponse'
              example:
                success: true
                message: Sub-merchant created successfully
                data:
                  id: '6182929449'
                  settlement_details:
                    bank_account_number: '9876543210'
                    bank_account_name: GlobalTech Solutions Inc.
                    bank_swift_code: CHASUS33XXX
                    bank_name: JPMorgan Chase Bank
                    bank_branch_name: Corporate Banking Division
                    bank_address: 270 Park Avenue
                    bank_city: New York
                    bank_state: NY
                    bank_country: United States
                    bank_pincode: '10017'
                    routing_number: '021000021'
                    settlement_currency: USD
                  created_at: '2025-01-15T10:30:00.000000Z'
                  company_details:
                    legal_name: GlobalTech Solutions Inc.
                    brand_name: GlobalTech
                    registration_number: US-CORP-99887766
                    international_org_type: Private Limited Company
                    tax_id: 94-1234567
                    website: https://www.globaltech.io
                    monthly_avg_transaction_volume: BETWEEN_20_K_AND_50_K
                    communication_address: 500 Mission Street, Suite 2400
                    communication_city: San Francisco
                    communication_state: CA
                    communication_country: United States
                    communication_pincode: '94105'
                    same_as_registered_address: false
                    registered_address: 1600 Amphitheatre Parkway
                    registered_city: Mountain View
                    registered_state: CA
                    registered_country: United States
                    registered_pincode: '94043'
                    business_category: E-commerce (physical goods & cross-border shipping)
                    business_mode: b2b
                    hs_codes:
                      - '85234910'
                      - '84715000'
                    description_of_products_and_services: >-
                      GlobalTech provides cloud-native enterprise software,
                      including AI-powered analytics platforms, CRM solutions,
                      and infrastructure automation tools. We enable digital
                      transformation for Fortune 500 companies through scalable
                      and secure software systems.
                    agreement_details: >-
                      Master Service Agreement dated 2024-01-10 with Global
                      Clients
                    email: contact@example.com
                    phone_number: '+919876543210'
                    business_category_other: null
                  last_updated_at: '2025-01-15T10:30:00.000000Z'
                  kyc_status: PENDING
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: 40000
                  message: Invalid request
                  details:
                    settlement_details:
                      bank_account_number: This field is required.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_AUTH_003
                  message: This endpoint is only accessible to PSP merchants
                  details:
                    authentication: This endpoint is only accessible to PSP merchants.
      security:
        - clientAuth: []
          clientSecretAuth: []
          apiVersionHeader: []
components:
  schemas:
    v1_CreateMerchantRequest:
      type: object
      required:
        - settlement_details
        - company_details
      properties:
        settlement_details:
          $ref: '#/components/schemas/v1_SettlementDetails'
        company_details:
          $ref: '#/components/schemas/v1_CompanyDetails'
    v1_CreateMerchantResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message
        data:
          $ref: '#/components/schemas/v1_MerchantDetails'
    v1_ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
          description: >-
            Indicates if the request was successful. Always false for error
            responses.
        error:
          $ref: '#/components/schemas/v1_ErrorDetails'
    v1_SettlementDetails:
      type: object
      required:
        - bank_account_number
        - bank_account_name
        - bank_swift_code
        - bank_name
        - bank_branch_name
        - bank_address
        - bank_city
        - bank_state
        - bank_country
        - bank_pincode
        - routing_number
      properties:
        bank_account_number:
          type: string
          description: Bank account number
        bank_account_name:
          type: string
          description: Name on the bank account
        bank_swift_code:
          type: string
          description: Bank SWIFT/BIC code
        bank_name:
          type: string
          description: Name of the bank
        bank_branch_name:
          type: string
          description: Bank branch name
        bank_address:
          type: string
          description: Bank address
        bank_city:
          type: string
          description: Bank city
        bank_state:
          type: string
          description: Bank state
        bank_country:
          type: string
          description: Bank country
        bank_pincode:
          type: string
          description: Bank pincode/postal code
        routing_number:
          type: string
          description: Bank routing number
    v1_CompanyDetails:
      type: object
      required:
        - email
        - phone_number
        - legal_name
        - brand_name
        - registration_number
        - international_org_type
        - tax_id
        - website
        - monthly_avg_transaction_volume
        - business_category
        - business_mode
        - description_of_products_and_services
        - registered_address
        - registered_city
        - registered_state
        - registered_country
        - registered_pincode
        - same_as_registered_address
      properties:
        legal_name:
          type: string
          description: Legal name of the company
        brand_name:
          type: string
          description: Brand/trading name of the company
        registration_number:
          type: string
          description: Company registration number
        international_org_type:
          type: string
          enum:
            - Private Limited Company
            - Public Limited Company
            - Limited Liability Company
            - Joint Stock Company
            - Free Zone Company / Entity
            - Partnership / LLP
            - Sole Proprietorship
            - Other
          description: Type of organization
        tax_id:
          type: string
          description: Tax identification number
        website:
          type: string
          format: uri
          description: Company website URL (must include https://)
        monthly_avg_transaction_volume:
          type: string
          enum:
            - LESS_THAN_5_K
            - BETWEEN_5_K_AND_20_K
            - BETWEEN_20_K_AND_50_K
            - BETWEEN_50_K_AND_100_K
            - BETWEEN_100_K_AND_250_K
            - BETWEEN_250_K_AND_500_K
            - ABOVE_500_K
          description: Expected monthly transaction volume range
        registered_address:
          type: string
          description: Registered address
        registered_city:
          type: string
          description: Registered city
        registered_state:
          type: string
          description: Registered state
        registered_country:
          type: string
          description: Registered country
        registered_pincode:
          type: string
          description: Registered pincode/postal code
        same_as_registered_address:
          type: boolean
          description: >-
            Whether communication address is same as registered address, if
            provided communication address will be ignored
        communication_address:
          type: string
          description: >-
            Communication address, required if same_as_registered_address is
            false or not provided
        communication_city:
          type: string
          description: >-
            Communication city, required if same_as_registered_address is false
            or not provided
        communication_state:
          type: string
          description: >-
            Communication state, required if same_as_registered_address is false
            or not provided
        communication_country:
          type: string
          description: >-
            Communication country, required if same_as_registered_address is
            false or not provided
        communication_pincode:
          type: string
          description: >-
            Communication pincode/postal code, required if
            same_as_registered_address is false or not provided
        business_category:
          type: string
          description: >-
            Business category (comma-separated for multiple). Values: E-commerce
            (physical goods & cross-border shipping), Digital goods / software /
            downloads, SaaS / subscriptions / recurring billing, Services
            (delivered cross-border), Marketplace / platform (multiple sellers),
            Other
        business_mode:
          type: string
          enum:
            - b2b
            - b2c
            - marketplace
          description: Mode of business
        hs_codes:
          type: array
          items:
            type: string
          description: >-
            Harmonized System codes for products/services, required for physical
            goods
        description_of_products_and_services:
          type: string
          description: Detailed description of products and services
        agreement_details:
          type: string
          description: Agreement details
        email:
          type: string
          format: email
          description: Contact email for the sub-merchant
        phone_number:
          type: string
          description: Contact phone number in E.164 format (e.g., +919876543210)
        mcc:
          type: string
          description: Comma-separated 4-digit Merchant Category Codes (e.g., 5411,5812)
        business_category_other:
          type: string
          description: Required when business_category includes Other
    v1_MerchantDetails:
      type: object
      required:
        - id
        - settlement_details
        - created_at
        - company_details
        - last_updated_at
        - kyc_status
      properties:
        id:
          type: string
          description: Unique merchant identifier
        settlement_details:
          $ref: '#/components/schemas/v1_SettlementDetails'
        created_at:
          type: string
          format: date-time
          description: Merchant creation timestamp
        company_details:
          $ref: '#/components/schemas/v1_CompanyDetails'
        last_updated_at:
          type: string
          format: date-time
          description: Last updated timestamp
        kyc_status:
          type: string
          enum:
            - PENDING
            - IN_REVIEW
            - CHANGES_REQUESTED
            - APPROVED
            - REJECTED
          description: Current KYC/onboarding status
    v1_ErrorDetails:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code (e.g., ERR_ORDER_002)
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Detailed validation error information with field-specific errors
          additionalProperties:
            type: string
            description: Error message for the specific field
  securitySchemes:
    clientAuth:
      type: apiKey
      name: X-Client-ID
      in: header
      description: >-
        **Client Application ID** - Your unique application identifier used to
        authenticate API requests. You can find your Client ID in the Developer
        Settings section of the merchant dashboard.
      x-displayName: Client ID
      x-example: your-client-id
    clientSecretAuth:
      type: apiKey
      name: X-Client-Secret
      in: header
      description: >-
        **Client Secret Key** - Your secret key used alongside the Client ID for
        secure authentication. Keep this confidential and never expose it in
        client-side code. Available in the Developer Settings section of the
        merchant dashboard.
      x-displayName: Client Secret
      x-example: your-client-secret
    apiVersionHeader:
      type: apiKey
      name: X-API-Version
      in: header
      description: >-
        **API Version** - Specifies which version of the API to use (e.g.,
        '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which
        API version your integration uses. Default version information is
        available in the Developer Settings.
      x-displayName: API Version
      x-example: 3.0.0

````