Submerchants

5min

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.
﻿

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.

Payment Links

Android inter-app integration