Online Payment

Marketplace product offer multiple online payment methods. Followings are 4 different payment methods;

Payment Method Decision

Non-3DS

3DS

Checkout Form (CF)

PayWithiyzico (PWI)

If you also wish to sell as a submerchant or a marketplace owner, there are two methods available:

1. Either create a submerchant under your account and assign yourself to this submerchant as well as your products.

2. If you prefer to sell without creating a submerchant, you can use the paymentGroup parameter with the value LISTING. (Please note that when using this approach, the subMerchantKey parameter cannot be utilized.)

After choosing one of the four payment types, you will need to include two additional parameters: subMerchantKey and subMerchantPrice. It is essential to assign these parameters to each product in the payment request.

Input Name	Type	Require	Description
subMerchantKey	string	yes	Returned value from submerchant create request
subMerchantPrice	string	yes	Amount that needs to be transferred for sub merchant

Marketplace Payment (Non3D)

post

Example shows the Non3D method. In a marketplace flow, each basket split must include sub-merchant fields.

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-Typestring · enumRequired

Request body content type.

Example: application/jsonPossible values:

Body

application/json

Non3D payment request. In the marketplace model, each basket split must include sub-merchant fields.

localestring · enumOptional

Response language.

Example: enPossible values:

conversationIdstringOptional

Correlation value that is echoed back in the response.

Example: 123456789

pricedecimalRequired

Basket (cart) total. Sum of basket item prices must equal price.

Example: 100

paidPricedecimalRequired

Final amount to be charged at POS; can be less than, greater than, or equal to price.

Example: 100

currencystring · enumOptional

Payment currency (default TRY).

Example: TRYPossible values:

installmentinteger · enumOptional

Installment count. Default; 1

Example: 1Possible values:

paymentChannelstring · enumOptional

Payment channel. Default; "WEB"

Example: WEBPossible values:

basketIdstringOptional

Basket/order identifier on the merchant side.

Example: basketId

paymentGroupstring · enumOptional

Payment group.

Example: PRODUCTPossible values:

Responses

200

Success

application/json

400

Error

application/json

post

/payment/auth

HTTPcURL

POST https://api.iyzipay.com/payment/auth
Authorization: {{authorization}}
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "price": 100.0,
  "paidPrice": 100.0,
  "currency": "TRY",
  "installment": 1,
  "paymentChannel": "WEB",
  "basketId": "basketId",
  "paymentGroup": "PRODUCT",
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5526080000000006",
    "expireYear": "2025",
    "expireMonth": "12",
    "cvc": "123",
    "registerCard": 0
  },
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "74300864791",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "basketItems": [
    {
      "id": "BI103",
      "name": "Usb",
      "price": 100.0,
      "category1": "Electronics",
      "category2": "Usb / Cable",
      "itemType": "PHYSICAL",
      "subMerchantKey": "n621Bd1zi4vpW/uVkMc8vCnwTPk=",
      "subMerchantPrice": 94.2,
      "withholdingTax": 0.8
    }
  ]
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1756197410420,
  "conversationId": "123456789",
  "price": 100,
  "paidPrice": 100,
  "installment": 1,
  "paymentId": "25223114",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 3.49,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "basketId",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI103",
      "paymentTransactionId": "27212232",
      "transactionStatus": 1,
      "price": 100,
      "paidPrice": 100,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 3.49,
      "iyziCommissionFee": 0.25,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "withholdingTax": 0.8,
      "blockageResolvedDate": "2025-09-02 11:36:50",
      "subMerchantKey": "n621Bd1zi4vpW/uVkMc8vCnwTPk=",
      "externalSubMerchantId": "ExternalId31",
      "subMerchantPrice": 94.2,
      "subMerchantPayoutRate": 94.2,
      "subMerchantPayoutAmount": 94.2,
      "merchantPayoutAmount": 2.06,
      "convertedPayout": {
        "paidPrice": 100,
        "iyziCommissionRateAmount": 3.49,
        "iyziCommissionFee": 0.25,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 94.2,
        "merchantPayoutAmount": 2.06,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "038911",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "8ab2a15666c4687a47d2f3144034d732e5dae1d3b3a3a07b35823493fffe109e"
}

Sample Codes

PHP

Java

.Net

Node.Js

Python

Postman