Submerchant

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

application/json

The request body varies depending on subMerchantType.

or

or

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

HTTP (Personal)HTTP (Private Company)HTTP (Limited/Joint-Stock)

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": "[phone]",
  "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İ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="
}

Update Submerchant

put

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.

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

application/json

Update fields vary by submerchant type. Do not send subMerchantType in update.

or

or

Responses

200

Successful response

application/json

statusstring · enumOptional

Result.

Example: successPossible values:

localestring · enumOptional

Response language.

Example: enPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755857408023

conversationIdstringOptional

ID sent in the request.

Example: 123456789

400

Error response

application/json

put

/onboarding/submerchant

HTTP (Personal)HTTP (Private Company)HTTP (Limited/Joint-Stock)

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

{
  "locale": "en",
  "conversationId": "conversationId",
  "name": "Jane2's market",
  "email": "[email protected]",
  "gsmNumber": "[phone]",
  "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
  "iban": "TR180006200119000006672315",
  "contactName": "Jane",
  "contactSurname": "Doe",
  "currency": "TRY",
  "identityNumber": "11111111111",
  "subMerchantKey": "wkF6Nkyn01vmTDNErfJtYkNoFAw="
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755857408023,
  "conversationId": "123456789"
}

Get Submerchant Detail

post

Returns submerchant details by external ID (subMerchantExternalId).

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

application/json

localestring · enumOptionalExample: enPossible values:

conversationIdstringOptionalExample: 123456789

subMerchantExternalIdstringRequired

ExternalId of the submerchant to query.

Example: S49222

Responses

200

Successful response

application/json

statusstring · enumOptionalExample: successPossible values:

localestring · enumOptionalExample: enPossible values:

systemTimeintegerOptionalExample: 1686439210683

conversationIdstringOptionalExample: 123456789

namestringOptionalExample: Jane's market

emailstringOptionalExample: [email protected]

gsmNumberstringOptionalExample: [phone]

addressstringOptionalExample: Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul

ibanstringOptionalExample: TR180006200119000006672315

bankCountrystringOptionalExample: TR

currencystringOptionalExample: TRY

taxOfficestringOptionalExample: Tax office

legalCompanyTitlestringOptionalExample: Jane Doe inc

subMerchantExternalIdstringOptionalExample: S49222

identityNumberstringOptional

National ID (TCKN).

Example: 11111111111

subMerchantTypestringOptionalExample: PRIVATE_COMPANY

subMerchantKeystringOptionalExample: //1GpuCHXkofxapmacyoimf6u/o=

400

Error response

application/json

post

/onboarding/submerchant/detail

HTTPcURL

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

{
  "locale": "en",
  "conversationId": "123456789",
  "subMerchantExternalId": "S49222"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1686439210683,
  "conversationId": "123456789",
  "name": "Jane's market",
  "email": "[email protected]",
  "gsmNumber": "[phone]",
  "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
  "iban": "TR180006200119000006672315",
  "bankCountry": "TR",
  "currency": "TRY",
  "taxOffice": "Tax office",
  "legalCompanyTitle": "Jane Doe inc",
  "subMerchantExternalId": "S49222",
  "identityNumber": "11111111111",
  "subMerchantType": "PRIVATE_COMPANY",
  "subMerchantKey": "//1GpuCHXkofxapmacyoimf6u/o="
}

Submerchant Item/Price Update

put

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

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

application/json

localestring · enumOptionalExample: enPossible values:

conversationIdstringOptionalExample: 123456789

paymentTransactionIdstringRequired

Payment split id.

Example: 20947104

subMerchantKeystringRequired

Submerchant key.

Example: favC6OGPAVHb97HwXG5GPKd4KuE=

subMerchantPricenumberRequired

Amount to be transferred to the submerchant.

Example: 11

Responses

200

Successful response

application/json

statusstring · enumOptionalExample: successPossible values:

localestring · enumOptionalExample: enPossible values:

systemTimeintegerOptionalExample: 1686442628687

conversationIdstringOptionalExample: 123456789

itemIdstringOptionalExample: BI102

paymentTransactionIdstringOptionalExample: 20947104

transactionStatusintegerOptionalExample: 1

pricenumberOptionalExample: 50

paidPricenumberOptionalExample: 50

merchantCommissionRatenumberOptionalExample: 0

merchantCommissionRateAmountnumberOptionalExample: 0

iyziCommissionRateAmountnumberOptionalExample: 2

iyziCommissionFeenumberOptionalExample: 0.125

blockageRatenumberOptionalExample: 0

blockageRateAmountMerchantnumberOptionalExample: 0

blockageRateAmountSubMerchantnumberOptionalExample: 0

blockageResolvedDatestringOptionalExample: 2023-06-19 00:00:00

subMerchantKeystringOptionalExample: favC6OGPAVHb97HwXG5GPKd4KuE=

subMerchantPricenumberOptionalExample: 11

subMerchantPayoutRatenumberOptionalExample: 22

subMerchantPayoutAmountnumberOptionalExample: 11

merchantPayoutAmountnumberOptionalExample: 36.875

400

Error response

application/json

put

/payment/item

HTTPcURL

PUT https://api.iyzipay.com/payment/item
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "paymentTransactionId" : "20947104",
  "subMerchantKey" : "favC6OGPAVHb97HwXG5GPKd4KuE=",
  "subMerchantPrice" : "11.0"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1686442628687,
  "conversationId": "123456789",
  "itemId": "BI102",
  "paymentTransactionId": "20947104",
  "transactionStatus": 1,
  "price": 50,
  "paidPrice": 50,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 2,
  "iyziCommissionFee": 0.125,
  "blockageRate": 0,
  "blockageRateAmountMerchant": 0,
  "blockageRateAmountSubMerchant": 0,
  "blockageResolvedDate": "2023-06-19 00:00:00",
  "subMerchantKey": "favC6OGPAVHb97HwXG5GPKd4KuE=",
  "subMerchantPrice": 11,
  "subMerchantPayoutRate": 22,
  "subMerchantPayoutAmount": 11,
  "merchantPayoutAmount": 36.875,
  "convertedPayout": {
    "paidPrice": 50,
    "iyziCommissionRateAmount": 2,
    "iyziCommissionFee": 0.125,
    "blockageRateAmountMerchant": 0,
    "blockageRateAmountSubMerchant": 0,
    "subMerchantPayoutAmount": 11,
    "merchantPayoutAmount": 36.875,
    "iyziConversionRate": 0,
    "iyziConversionRateAmount": 0,
    "currency": "TRY"
  }
}