---
title: Submerchants
slug: submerchants
docTags: 
createdAt: 2024-05-07T22:10:18.163Z
---

## Create Submerchant

Creates a new submerchant resource.

### Request

- Method: `POST`
- Endpoint: `/submerchants`
- Content-Type: `application/json`

### Request Body

The request body should be a JSON object containing the following properties:

| Property                     | Type    | Required | Description                                                                                                                                        |
| ---------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isActive`                   | boolean | No       | Indicates whether the submerchant is active. Default is `true`.                                                                                    |
| `payoutsWithheld`            | boolean | No       | Indicates whether payouts are withheld for the submerchant. Default is `false`.                                                                    |
| `payoutsWithheldReason`      | string  | No       | The reason for withholding payouts. Required when `payoutsWithheld` is `true`. Must be one of the allowed `payoutsWithheldReasons`.                |
| `payoutsWithheldMessage`     | string  | No       | The message associated with withholding payouts. Required when `payoutsWithheld` is `true`.                                                        |
| `name`                       | string  | Yes      | The name of the submerchant.                                                                                                                       |
| `legalName`                  | string  | No       | The legal name of the submerchant.                                                                                                                 |
| `businessType`               | string  | No       | The type of business. Default is `sole_proprietorship`. Must be one of the allowed `businessTypes`.                                                |
| `businessRegistrationNumber` | string  | No       | The business registration number. Required when `businessType` is not `sole_proprietorship`.                                                       |
| `phoneNumber`                | string  | Yes      | The phone number of the submerchant in E.164 format.                                                                                               |
| `secondaryPhoneNumber`       | string  | No       | The secondary phone number of the submerchant in E.164 format.                                                                                     |
| `emailAddress`               | string  | No       | The email address of the submerchant.                                                                                                              |
| `websiteUrl`                 | string  | No       | The website URL of the submerchant.                                                                                                                |
| `addressLine1`               | string  | Yes      | The first line of the submerchant's address.                                                                                                       |
| `addressLine2`               | string  | No       | The second line of the submerchant's address.                                                                                                      |
| `addressLine3`               | string  | No       | The third line of the submerchant's address.                                                                                                       |
| `addressCity`                | string  | Yes      | The city/town of the submerchant's address.                                                                                                        |
| `regionCode`                 | string  | Yes      | The region code of the submerchant's address. Must be one of the allowed `regionCodes`.                                                            |
| `postcode`                   | string  | Yes      | The postcode of the submerchant's address.                                                                                                         |
| `countryCode`                | string  | Yes      | The country code of the submerchant's address. Must be one of the allowed `countryCodes`.                                                          |
| `currencyCode`               | string  | No       | The currency code for the submerchant. Default is `gbp`. Must be one of the allowed `currencyCodes`.                                               |
| `inheritOperatorDbaInfo`     | boolean | No       | Indicates whether to inherit DBA information from the operator.                                                                                    |
| `language`                   | string  | No       | The language code for the submerchant. Default is `en`. Must be one of the allowed `languageCodes`.                                                |
| `signatory`                  | object  | Yes      | The signatory object representing the submerchant's signatory. Must conform to the `signatorySchema`.                                              |
| `significantOwners`          | array   | Yes      | An array of significant owner objects representing the submerchant's significant owners. Each object must conform to the `significantOwnerSchema`. |
| `merchantCategoryCode`       | string  | Yes      | The merchant category code (MCC) for the submerchant. Must be a valid MCC number.                                                                  |
| `merchantId`                 | string  | Yes      | The ID of the associated merchant. (Note: This will be removed in the future)                                                                      |
| `paymentFacilitatorId`       | string  | Yes      | The ID of the associated payment facilitator. (Note: This will become required in the future)                                                      |
| `operatorId`                 | string  | No       | The ID of the associated operator.                                                                                                                 |
| `reference`                  | string  | No       | An optional reference for the submerchant.                                                                                                         |
| `note`                       | string  | No       | An optional note for the submerchant.                                                                                                              |
| `businessDescription`        | string  | No       | A description of the submerchant's business. Maximum length is 400 characters.                                                                     |

### Response

- Status Code: `201 Created`
- Content-Type: `application/json`

The response body will contain the created submerchant resource.

### Errors

- `400 Bad Request` - The request body is invalid or missing required fields.
- `401 Unauthorized` - The request lacks valid authentication credentials.
- `403 Forbidden` - The authenticated user does not have sufficient permissions to create a submerchant.
- `500 Internal Server Error` - An unexpected error occurred on the server.