Submerchant

After the approval of the marketplace transaction, submerchants are required to have records at iyzico APIs to facilitate the money transfer. Since the merchant already has access to the submerchant details such like, email, address, name, taxoffice, it can be seamlessly transmitted to the iyzico Onboarding API for submerchant account creation and updates.

Submerchant Services

Submerchant Creation

Possible submerchants can be one of the following 3 types:

PERSONAL
PRIVATE COMPANY
LIMITED OR JOINT STOCK COMPANY

The parameters sent during the sub-merchant registration process may vary depending on the specific transaction type. Upon the completion of a sub-merchant registration, the response will include a unique subMerchantKey assigned to that particular seller. It is essential to securely store this value within your system, as you will need to provide the subMerchantKey when identifying the seller during the payment process.

When transmitting parameters to iyzico, it is crucial to ensure that all values are genuine and accurately reflect the required information. Please refrain from sending random, test, or non-authentic data.

Create Submerchant

post

Creates a submerchant for the marketplace model. Supported types are PERSONAL, PRIVATE_COMPANY, and LIMITED_OR_JOINT_STOCK_COMPANY. The subme rchant type is selected via the subMerchantType parameter.

Header parameters

AuthorizationstringRequired

Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Request body content type.

Example: application/json

Body

The request body varies depending on subMerchantType.

Responses

200

Successful response

application/json

statusstring · enumOptional

Result.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Operation time (epoch ms).

conversationIdstringOptional

ID sent in the request.

subMerchantKeystringOptional

Generated Submerchant key.

Example: wt6aF2hwJpms2w7AhTBTW5le9kM=

400

Error response

application/json

post

/onboarding/submerchant

POST https://api.iyzipay.com/onboarding/submerchant
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "conversationId",
  "name": "John's market Test",
  "email": "[email protected]",
  "gsmNumber": "+905350000000",
  "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
  "iban": "TR180006200119000006672315",
  "contactName": "John",
  "contactSurname": "Doe",
  "currency": "TRY",
  "subMerchantExternalId": "ExternalId",
  "identityNumber": "11111111111",
  "subMerchantType": "PERSONAL"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755847240070,
  "conversationId": "conversationId",
  "subMerchantKey": "wt6aF2hwJpms2w7AhTBTW5le9kM="
}