# Submerchant

## Create Submerchant

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

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"post":{"summary":"Create Submerchant","description":"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.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantCreateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantCreateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointRequest"}],"discriminator":{"propertyName":"subMerchantType","mapping":{"PERSONAL":"#/components/schemas/SubmerchantPersonalRequest","PRIVATE_COMPANY":"#/components/schemas/SubmerchantPrivateCompanyRequest","LIMITED_OR_JOINT_STOCK_COMPANY":"#/components/schemas/SubmerchantLimitedJointRequest"}},"description":"The request body varies depending on **subMerchantType**."},"SubmerchantPersonalRequest":{"description":"Personal Submerchant","type":"object","required":["subMerchantType","email","gsmNumber","address","contactName","contactSurname","subMerchantExternalId","identityNumber"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use PERSONAL for personal accounts."},"name":{"type":"string","description":"Submerchant (store) name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must be consistent with **contactName/contactSurname**. If not sent during creation, it must be provided before product approval for payouts.\n"},"contactName":{"type":"string","description":"Contact first name."},"contactSurname":{"type":"string","description":"Contact last name."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant to map your Submerchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"conversationId":{"type":"string","description":"Correlation id for request/response."}}},"SubmerchantPrivateCompanyRequest":{"description":"Private Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"PRIVATE_COMPANY\" for private companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone (E.164)."},"address":{"type":"string","description":"Submerchantt address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointRequest":{"description":"Limited/Joint-Stock Company","type":"object","required":["subMerchantType","email","gsmNumber","address","taxOffice","taxNumber","legalCompanyTitle","subMerchantExternalId"],"properties":{"subMerchantType":{"type":"string","enum":["PERSONAL","PRIVATE_COMPANY","LIMITED_OR_JOINT_STOCK_COMPANY"],"description":"Submerchant type. Use \"LIMITED_OR_JOINT_STOCK_COMPANY\" for LTD/JSC companies."},"name":{"type":"string","description":"Submerchant name."},"email":{"type":"string","description":"Submerchant email."},"gsmNumber":{"type":"string","description":"Submerchant phone."},"address":{"type":"string","description":"Submerchant address."},"iban":{"type":"string","description":"Submerchant IBAN. Must match **legalCompanyTitle**. If not sent during creation, it must be provided before product approval for payouts.\n"},"taxOffice":{"type":"string","description":"Tax office."},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string","description":"Registered company title."},"subMerchantExternalId":{"type":"string","description":"External unique id set by the merchant."},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"],"description":"Currency (default TRY)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantCreateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."},"subMerchantKey":{"type":"string","description":"Generated Submerchant key."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Update Submerchant

> Updates an existing submerchant. The request body shape varies by submerchant type; \*\*one of three variants\*\* must be sent. The \*\*subMerchantType\*\* field is \*\*not\*\* included in the update body.<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant":{"put":{"summary":"Update Submerchant","description":"Updates an existing submerchant. The request body shape varies by submerchant type; **one of three variants** must be sent. The **subMerchantType** field is **not** included in the update body.\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantUpdateRequest":{"oneOf":[{"$ref":"#/components/schemas/SubmerchantPersonalUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantPrivateCompanyUpdateRequest"},{"$ref":"#/components/schemas/SubmerchantLimitedJointUpdateRequest"}],"description":"Update fields vary by submerchant type. **Do not send subMerchantType** in update."},"SubmerchantPersonalUpdateRequest":{"description":"Personal Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","contactName","contactSurname","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string","description":"Store name."},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"contactName":{"type":"string"},"contactSurname":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantKey":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantPrivateCompanyUpdateRequest":{"description":"Private Company Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"legalCompanyTitle":{"type":"string"},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantLimitedJointUpdateRequest":{"description":"Limited/Joint-Stock Submerchant Update","type":"object","required":["email","gsmNumber","address","iban","legalCompanyTitle","taxOffice","identityNumber","subMerchantKey"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"taxNumber":{"type":"string","description":"Tax number."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","RUB","CHF","NOK"]},"subMerchantKey":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"}}},"SubmerchantUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent in the request."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Get Submerchant Detail

> Returns submerchant details by external ID (\*\*subMerchantExternalId\*\*).

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/onboarding/submerchant/detail":{"post":{"summary":"Get Submerchant Detail","description":"Returns submerchant details by external ID (**subMerchantExternalId**).","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmerchantDetailResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"SubmerchantDetailRequest":{"type":"object","required":["subMerchantExternalId"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"subMerchantExternalId":{"type":"string","description":"ExternalId of the submerchant to query."}}},"SubmerchantDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"gsmNumber":{"type":"string"},"address":{"type":"string"},"iban":{"type":"string"},"bankCountry":{"type":"string"},"currency":{"type":"string"},"taxOffice":{"type":"string"},"legalCompanyTitle":{"type":"string"},"subMerchantExternalId":{"type":"string"},"identityNumber":{"type":"string","description":"National ID (TCKN)."},"subMerchantType":{"type":"string"},"subMerchantKey":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```

## Submerchant Item/Price Update

> This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction<br>

```json
{"openapi":"3.0.3","info":{"title":"Marketplace - Submerchant Create & Update - Approve","version":"1.3.3"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/item":{"put":{"summary":"Submerchant Item/Price Update","description":"This service is used to modify the payout amount of the submerchant or update the submerchant information based on a single paymentTransaction\n","tags":["Marketplace"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPayoutUpdateResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ItemPayoutUpdateRequest":{"type":"object","required":["paymentTransactionId","subMerchantPrice","subMerchantKey"],"properties":{"locale":{"type":"string","enum":["tr","en"]},"conversationId":{"type":"string"},"paymentTransactionId":{"type":"string","description":"Payment split id."},"subMerchantKey":{"type":"string","description":"Submerchant key."},"subMerchantPrice":{"type":"number","description":"Amount to be transferred to the submerchant."}}},"ItemPayoutUpdateResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"},"itemId":{"type":"string"},"paymentTransactionId":{"type":"string"},"transactionStatus":{"type":"integer"},"price":{"type":"number"},"paidPrice":{"type":"number"},"merchantCommissionRate":{"type":"number"},"merchantCommissionRateAmount":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRate":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"blockageResolvedDate":{"type":"string"},"subMerchantKey":{"type":"string"},"subMerchantPrice":{"type":"number"},"subMerchantPayoutRate":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"convertedPayout":{"type":"object","properties":{"paidPrice":{"type":"number"},"iyziCommissionRateAmount":{"type":"number"},"iyziCommissionFee":{"type":"number"},"blockageRateAmountMerchant":{"type":"number"},"blockageRateAmountSubMerchant":{"type":"number"},"subMerchantPayoutAmount":{"type":"number"},"merchantPayoutAmount":{"type":"number"},"iyziConversionRate":{"type":"number"},"iyziConversionRateAmount":{"type":"number"},"currency":{"type":"string"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"]},"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer"},"conversationId":{"type":"string"}}}}}}
```