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

Successful Non3D payment response.

statusstring · enumOptional

Operation result.

Example: successPossible values:

localestring · enumOptional

Response language.

Example: enPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1756197410420

conversationIdstringOptional

Correlation ID.

Example: 123456789

pricedecimalOptional

Basket total.

Example: 100

paidPricedecimalOptional

Charged total amount (via POS).

Example: 100

installmentintegerOptional

Installment count.

Example: 1

paymentIdstringOptional

iyzico payment ID.

Example: 25223114

fraudStatusinteger · enumOptional

Fraud filter result:

• 1: Approved — merchant may proceed (ship).
• 0: Under review — wait for a later notification.
• -1: Rejected.

Example: 1Possible values:

merchantCommissionRatedecimalOptional

Merchant commission rate.

Example: 0

merchantCommissionRateAmountdecimalOptional

Merchant commission amount.

Example: 0

iyziCommissionRateAmountdecimalOptional

iyzico commission rate amount.

Example: 3.49

iyziCommissionFeedecimalOptional

iyzico fixed fee.

Example: 0.25

cardTypestringOptional

Card type.

Example: CREDIT_CARD

cardAssociationstringOptional

Card scheme.

Example: MASTER_CARD

cardFamilystringOptional

Card family/brand.

Example: Axess

binNumberstringOptional

First 6 digits of the card.

Example: 552608

lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006

basketIdstringOptional

Basket ID.

Example: basketId

currencystringOptional

Currency.

Example: TRY

authCodestringOptional

Bank authorization code.

Example: 038911

phasestringOptional

Transaction phase (AUTH/PREAUTH etc.).

Example: AUTH

hostReferencestringOptional

Host reference.

Example: mock00007iyzihostrfn

signaturestringOptional

Response signature (for verification).

Example: 8ab2a1...fffe109e

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