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

• Submerchant Update

• Submerchant Details

• Submerchant Item Update

Submerchant Creation

Possible submerchants can be one of the following 3 types:

1. Individual

2. Sole Proprietorship

3. Limited/Incorporated 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.

Individual Submerchant Request

POST https://api.iyzipay.com/onboarding/submerchant

Request Body

Name	Type	Description
locale	String	Language (default: tr)
conversationId	String	If set, conversation ID to match request and response
subMerchantExternalId*	String	Merchant identification number on your system
subMerchantType*	String	The PERSONAL value must be sent for the individual type of submerchants .
address*	String	Address of submerchant
contactName*	String	Contact name of submerchant
contactSurname*	String	Surname of submerchant
email*	String	Email of submerchant
gsmNumber	String	GSM of submerchant
name	String	Name of submerchant
iban	String	IBAN of submerchant. Its expected that contactName and contactSurname matches with IBAN. Even if it left blank while creating the submerchant, it must be filled before approving the payment.
identityNumber	String	ID of submerchant
currency	String	Default is TL. Alternatives; USD, EUR, GBP, CHF and NOK

Sole Proprietorship Submerchant Request

POST https://api.iyzipay.com/onboarding/submerchant

Request Body

Name	Type	Description
locale	String	Language (default: tr)
conversationId	String	If set, conversation ID to match request and response
subMerchantExternalId*	String	Merchant identification number on your system
subMerchantType*	String	The PRIVATE_COMPANY value must be sent for the sole proprietorshop type of submerchants .
address*	String	Address of submerchant
contactName*	String	Contact name of submerchant
contactSurname*	String	Surname of submerchant
email*	String	Email of submerchant
gsmNumber	String	GSM of submerchant
name	String	Name of submerchant
iban	String	IBAN of submerchant. Its expected that contactName and contactSurname matches with IBAN. Even if it left blank while creating the submerchant, it must be filled before approving the payment.
identityNumber	String	ID of submerchant
currency	String	Default is TL. Alternatives; USD, EUR, GBP, CHF and NOK
taxOffice	String	Tax office of submerchant
legalCompanyTitle	String	Legal Company Title of submerchant

200: OK

Limited/Incorporated Company Submerchant Request

POST https://api.iyzipay.com/onboarding/submerchant

Request Body

Name	Type	Description
locale	String	Language (default: tr)
conversationId	String	If set, conversation ID to match request and response
subMerchantExternalId*	String	Merchant identification number on your system
subMerchantType*	String	The LIMITED_OR_JOINT_STOCK_COMPANY value must be sent for the sole proprietorshop type of submerchants .
address*	String	Address of submerchant
contactName*	String	Contact name of submerchant
contactSurname*	String	Surname of submerchant
email*	String	Email of submerchant
gsmNumber	String	GSM of submerchant
name	String	Name of submerchant
iban	String	IBAN of submerchant. Its expected that contactName and contactSurname matches with IBAN. Even if it left blank while creating the submerchant, it must be filled before approving the payment.
identityNumber	String	ID of submerchant
currency	String	Default is TL. Alternatives; USD, EUR, GBP, CHF and NOK
legalCompanyTitle	String	Legal Company Title of submerchant
taxNumber*	String	Tax number of submerchant
taxOffice*	String	Tax office of submerchant

200: OK

Submerchant Creation Response

Output Name	Type	Description
subMerchantKey	String	Key of submerchant
status	String	Service response result (success / failure)
errorCode	String	Error code if service response status is failure
errorMessage	String	Error message if service response status is failure
errorGroup	String	Error group if service response status is failure
locale	String	Language (default: tr)
systemTime	Integer	Response system timestamp value
conversationId	String	If set, conversation ID to match request and response

Submerchant Creation Sample Codes

Individual Submerchant Creation Request;

PHP

$request = new \Iyzipay\Request\CreateSubMerchantRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId("123456789");
$request->setSubMerchantExternalId("S49222");
$request->setSubMerchantType(\Iyzipay\Model\SubMerchantType::PERSONAL);
$request->setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$request->setContactName("John");
$request->setContactSurname("Doe");
$request->setEmail("[e-mail]");
$request->setGsmNumber("[phone]");
$request->setName("John's market");
$request->setIban("TR180006200119000006672315");
$request->setIdentityNumber("31300864726");
$request->setCurrency(\Iyzipay\Model\Currency::TL);

$subMerchant = \Iyzipay\Model\SubMerchant::create($request, Config::options());

.NET

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.Locale = Locale.TR.ToString();
request.ConversationId = "123456789";
request.SubMerchantExternalId = "S49222";
request.SubMerchantType = SubMerchantType.PERSONAL.ToString();
request.Address = "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1";
request.ContactName = "John";
request.ContactSurname = "Doe";
request.Email = "[e-mail]";
request.GsmNumber = "[phone]";
request.Name = "John's market";
request.Iban = "TR180006200119000006672315";
request.IdentityNumber = "31300864726";
request.Currency = Currency.TRY.ToString();

SubMerchant subMerchant = SubMerchant.Create(request, options);

JAVA

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setSubMerchantExternalId("S49222");
request.setSubMerchantType(SubMerchantType.PERSONAL.name());
request.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
request.setContactName("John");
request.setContactSurname("Doe");
request.setEmail("[e-mail]");
request.setGsmNumber("[phone]");
request.setName("John's market");
request.setIban("TR180006200119000006672315");
request.setIdentityNumber("31300864726");
request.setCurrency(Currency.TRY.name());

SubMerchant subMerchant = SubMerchant.create(request, options);

NodeJS

iyzipay.subMerchant.create({
    locale: Iyzipay.LOCALE.TR,
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay.SUB_MERCHANT_TYPE.PERSONAL,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    ContactName: 'John',
    ContactSurname: 'Doe',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    identityNumber: '31300864726',
    currency: Iyzipay.CURRENCY.TRY
}, function (err, result) {
    console.log(err, result);
    done();
});

Python

request = dict([('locale', 'tr')])
request['conversationId'] = '123456789'
request['subMerchantExternalId'] = 'S49222'
request['subMerchantType'] = 'PERSONAL'
request['address'] = 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1'
request['ContactName'] = 'John'
request['ContactSurname'] = 'Doe'
request['email'] = '[e-mail]'
request['gsmNumber'] = '[phone]'
request['name'] = 'John\'s market'
request['iban'] = 'TR180006200119000006672315'
request['identityNumber'] = '31300864726'
request['currency'] = 'TRY'

sub_merchant = iyzipay.SubMerchant()
sub_merchant_response = sub_merchant.create(request, options)

Ruby

request = {
    locale: 'tr',
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay::Model::SubMerchantType::PERSONAL,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    ContactName: 'John',
    ContactSurname: 'Doe',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    identityNumber: '31300864726',
    currency: Iyzipay::Model::Currency::TRY
}
sub_merchant = Iyzipay::Model::SubMerchant.new.create(request, @options)

JSON

//Request
{
    "locale": "tr",
    "conversationId": "123456789",
    "name": "John's market",
    "email": "[e-mail]",
    "gsmNumber": "[phone]",
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "iban": "TR180006200119000006672315",
    "ContactName": "John",
    "ContactSurname": "Doe",
    "currency": "TRY",
    "subMerchantExternalId": "S49222",
    "identityNumber": "31300864726",
    "subMerchantType": "PERSONAL"
}

//Response
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1470732341410,
    "conversationId": "123456789",
    "subMerchantKey": "PPFFZPedVQSvaOqZu5xpvpLEqmc="
}

Sole Proprietorship Submerchant Creation Request;

PHP

$request = new \Iyzipay\Request\CreateSubMerchantRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId("123456789");
$request->setSubMerchantExternalId("S49222");
$request->setSubMerchantType(\Iyzipay\Model\SubMerchantType::PRIVATE_COMPANY);
$request->setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$request->setTaxOffice("Tax office");
$request->setLegalCompanyTitle("John Doe inc");
$request->setEmail("[e-mail]");
$request->setGsmNumber("[phone]");
$request->setName("John's market");
$request->setIban("TR180006200119000006672315");
$request->setIdentityNumber("31300864726");
$request->setCurrency(\Iyzipay\Model\Currency::TL);

$subMerchant = \Iyzipay\Model\SubMerchant::create($request, Config::options());

.NET

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.Locale = Locale.TR.ToString();
request.ConversationId = "123456789";
request.SubMerchantExternalId = "S49222";
request.SubMerchantType = SubMerchantType.PRIVATE_COMPANY.ToString();
request.Address = "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1";
request.TaxOffice = "Tax office";
request.LegalCompanyTitle = "John Doe inc";
request.Email = "[e-mail]";
request.GsmNumber = "[phone]";
request.Name = "John's market";
request.Iban = "TR180006200119000006672315";
request.IdentityNumber = "31300864726";
request.Currency = Currency.TRY.ToString();

SubMerchant subMerchant = SubMerchant.Create(request, options);

JAVA

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setSubMerchantExternalId("S49222");
request.setSubMerchantType(SubMerchantType.PRIVATE_COMPANY.name());
request.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
request.setTaxOffice("Tax office");
request.setLegalCompanyTitle("John Doe inc");
request.setEmail("[e-mail]");
request.setGsmNumber("[phone]");
request.setName("John's market");
request.setIban("TR180006200119000006672315");
request.setIdentityNumber("31300864726");
request.setCurrency(Currency.TRY.name());

SubMerchant subMerchant = SubMerchant.create(request, options);

NodeJS

iyzipay.subMerchant.create({
    locale: Iyzipay.LOCALE.TR,
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay.SUB_MERCHANT_TYPE.PRIVATE_COMPANY,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    taxOffice: 'Tax office',
    legalCompanyTitle: 'John Doe inc',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    identityNumber: '31300864726',
    currency: Iyzipay.CURRENCY.TRY
}, function (err, result) {
    console.log(err, result);
    done();
});

Python

request = dict([('locale', 'tr')])
request['conversationId'] = '123456789'
request['subMerchantExternalId'] = 'S49222'
request['subMerchantType'] = 'PRIVATE_COMPANY'
request['address'] = 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1'
request['taxOffice'] = 'Tax Office'
request['legalCompanyTitle'] = 'John Doe inc'
request['email'] = '[e-mail]'
request['gsmNumber'] = '[phone]'
request['name'] = 'John\'s market'
request['iban'] = 'TR180006200119000006672315'
request['identityNumber'] = '31300864726'
request['currency'] = 'TRY'

sub_merchant = iyzipay.SubMerchant()
sub_merchant_response = sub_merchant.create(request, options)

Ruby

request = {
    locale: 'tr',
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay::Model::SubMerchantType::PRIVATE_COMPANY,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    taxOffice: 'Tax office',
    legalCompanyTitle: 'John Doe inc',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    identityNumber: '31300864726',
    currency: Iyzipay::Model::Currency::TRY
}
sub_merchant = Iyzipay::Model::SubMerchant.new.create(request, @options)

JSON

//Request
{
    "locale": "tr",
    "conversationId": "123456789",
    "name": "John's market",
    "email": "[e-mail]",
    "gsmNumber": "[phone]",
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "iban": "TR180006200119000006672315",
    "taxOffice": "Tax office",
    "legalCompanyTitle": "John Doe inc",
    "currency": "TRY",
    "subMerchantExternalId": "S49222",
    "identityNumber": "31300864726",
    "subMerchantType": "PRIVATE_COMPANY"
}

//Response
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1470732341410,
    "conversationId": "123456789",
    "subMerchantKey": "PPFFZPedVQSvaOqZu5xpvpLEqmc="
}

Limited/Incorporated Company Submerchant Creation Request;

PHP

$request = new \Iyzipay\Request\CreateSubMerchantRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId("123456789");
$request->setSubMerchantExternalId("S49222");
$request->setSubMerchantType(\Iyzipay\Model\SubMerchantType::LIMITED_OR_JOINT_STOCK_COMPANY);
$request->setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$request->setTaxOffice("Tax office");
$request->setTaxNumber("31300864726");
$request->setLegalCompanyTitle("John Doe inc");
$request->setEmail("[e-mail]");
$request->setGsmNumber("[phone]");
$request->setName("John's market");
$request->setIban("TR180006200119000006672315");
$request->setCurrency(\Iyzipay\Model\Currency::TL);

$subMerchant = \Iyzipay\Model\SubMerchant::create($request, Config::options());

.NET

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.Locale = Locale.TR.ToString();
request.ConversationId = "123456789";
request.SubMerchantExternalId = "S49222";
request.SubMerchantType = SubMerchantType.LIMITED_OR_JOINT_STOCK_COMPANY.ToString();
request.Address = "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1";
request.TaxOffice = "Tax office";
request.TaxNumber = "31300864726";
request.LegalCompanyTitle = "John Doe inc";
request.Email = "[e-mail]";
request.GsmNumber = "[phone]";
request.Name = "John's market";
request.Iban = "TR180006200119000006672315";
request.Currency = Currency.TRY.ToString();

SubMerchant subMerchant = SubMerchant.Create(request, options);

JAVA

CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setSubMerchantExternalId("S49222");
request.setSubMerchantType(SubMerchantType.LIMITED_OR_JOINT_STOCK_COMPANY.name());
request.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
request.setTaxOffice("Tax office");
request.setTaxNumber("31300864726");
request.setLegalCompanyTitle("John Doe inc");
request.setEmail("[e-mail]");
request.setGsmNumber("[phone]");
request.setName("John's market");
request.setIban("TR180006200119000006672315");
request.setCurrency(Currency.TRY.name());

SubMerchant subMerchant = SubMerchant.create(request, options);

NodeJS

iyzipay.subMerchant.create({
    locale: Iyzipay.LOCALE.TR,
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay.SUB_MERCHANT_TYPE.LIMITED_OR_JOINT_STOCK_COMPANY,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    taxOffice: 'Tax office',
    taxNumber: '31300864726',
    legalCompanyTitle: 'John Doe inc',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    currency: Iyzipay.CURRENCY.TRY
}, function (err, result) {
    console.log(err, result);
    done();
});

Python

request = dict([('locale', 'tr')])
request['conversationId'] = '123456789'
request['subMerchantExternalId'] = 'S49222'
request['subMerchantType'] = 'LIMITED_OR_JOINT_STOCK_COMPANY'
request['address'] = 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1'
request['taxOffice'] = 'Tax Office'
request['taxNumber'] = '31300864726'
request['legalCompanyTitle'] = 'John Doe inc'
request['email'] = '[e-mail]'
request['gsmNumber'] = '[phone]'
request['name'] = 'John\'s market'
request['iban'] = 'TR180006200119000006672315'
request['currency'] = 'TRY'

sub_merchant = iyzipay.SubMerchant()
sub_merchant_response = sub_merchant.create(request, options)

Ruby

request = {
    locale: 'tr',
    conversationId: '123456789',
    subMerchantExternalId: 'S49222',
    subMerchantType: Iyzipay::Model::SubMerchantType::LIMITED_OR_JOINT_STOCK_COMPANY,
    address: 'Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1',
    taxOffice: 'Tax office',
    taxNumber: '31300864726',
    legalCompanyTitle: 'John Doe inc',
    email: '[e-mail]',
    gsmNumber: '[phone]',
    name: 'John\'s market',
    iban: 'TR180006200119000006672315',
    currency: Iyzipay::Model::Currency::TRY
}
sub_merchant = Iyzipay::Model::SubMerchant.new.create(request, @options)

JSON

//Request
{
    "locale": "tr",
    "conversationId": "123456789",
    "name": "John's market",
    "email": "[e-mail]",
    "gsmNumber": "[phone]",
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "iban": "TR180006200119000006672315",
    "taxOffice": "Tax office",
    "taxNumber": "31300864726",
    "legalCompanyTitle": "John Doe inc",
    "currency": "TRY",
    "subMerchantExternalId": "S49222",
    "subMerchantType": "LIMITED_OR_JOINT_STOCK_COMPANY"
}

//Response
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1470732341410,
    "conversationId": "123456789",
    "subMerchantKey": "PPFFZPedVQSvaOqZu5xpvpLEqmc="
}