Create Payment

Create Payment API is responsible for processing the customer's card payments. When this service is used, iyzico provides an instant response regarding the success of the transaction.

• It supports transactions made with TROY, MASTERCARD, VISA, and AMEX branded cards.

• For cards participating in installment programs such as BONUS, WORLD, MAXIMUM, AXESS, CARDFINANS, PARAF, and ADVANTAGE, the service allows options for 2, 3, 6, 9, and 12 installments.

• Successful transactions are displayed in green, while failed transactions are displayed in red on the panel.

• The merchant can utilize the conversationId and basketId parameters as order numbers on their side.

By incorporating these features, you can provide a seamless payment experience for your customers, with real-time feedback on the success or failure of their transactions.

Create Non3D Payment

post

Initiates a payment without 3D Secure.

Header parameters

AuthorizationstringRequired

Authorization header starting with IYZWSv2 and a signed hash value encoded in base64.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

application/json

conversationIdstringOptional

Unique ID used to match request/response.

Example: conversationId

localestring · enumOptional

Language code. Allowed values; tr, en. Default; tr

Example: enPossible values:

paidPricedecimalRequired

Total amount to be charged from the buyer.

Example: 1

pricedecimalRequired

Basket total amount.

Example: 1

paymentGroupstring · enumOptional

Payment group. Default; PRODUCT.

Example: PRODUCTPossible values:

currencystring · enumRequired

Currency. Default; TRY.

Example: TRYPossible values:

installmentinteger · enumOptional

Installment count. If omitted, single payment (1) is applied.

Possible values:

basketIdstringOptional

Basket ID.

Example: B67832

paymentChannelstring · enumOptional

Payment channel.

Example: WEBPossible values:

Responses

200

Successful response

application/json

statusstring · enumOptional

Indicates the result of the request.

Example: successPossible values:

localestringOptional

Response language (tr/en).

Example: en

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941

conversationIdstringOptional

ID matching the request.

Example: conversationId

pricedecimalOptional

Basket total amount.

Example: 1

paidPricedecimalOptional

Total collected amount.

Example: 1

installmentintegerOptional

Installment count.

Example: 1

paymentIdstringOptional

Payment ID.

Example: 25149157

fraudStatusinteger · enumOptional

Payment status per fraud filters. If the risk score is low, the payment is approved instantly; if high, the payment is declined. The merchant should ship products only for transactions with value 1; for 0, the merchant should wait for notification.

• 1: Approved
• 0: Under review
• -1: Declined

Example: 1Possible values:

merchantCommissionRatedecimalOptional

Merchant's applied installment/commission rate. For example, if price=100 and paidPrice=110, the merchant rate is 10%. Informational.

Example: 0

merchantCommissionRateAmountdecimalOptional

Merchant's commission amount. For example, if price=100 and paidPrice=110, the commission amount is 10. Informational.

Example: 0

iyziCommissionRateAmountdecimalOptional

iyzico transaction commission amount.

Example: 0.2094

iyziCommissionFeedecimalOptional

iyzico transaction fee.

Example: 0.25

cardTypestring · enumOptional

Card type.

Example: CREDIT_CARDPossible values:

cardAssociationstring · enumOptional

Card association.

Example: MASTER_CARDPossible values:

cardFamilystring · enumOptional

Card family.

Example: AxessPossible values:

binNumberstringOptional

BIN (first 8 digits).

Example: 552608

lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006

basketIdstringOptional

Basket ID.

Example: basketId

currencystring · enumOptional

Currency.

Example: TRYPossible values:

authCodestringOptional

Auth code returned by the bank.

Example: 214525

phasestringOptional

Payment phase.

Example: AUTH

hostReferencestringOptional

Host reference value given by the bank for the payment.

Example: mock00001iyzihostrfn

signaturestringOptional

Signature value that can be used for signature verification.

Example: 5f510cd92b4b9c50a39b617cda228f4159f290860a4c20a965c55b119c9e9052

400

Invalid request / validation error

application/json

post

/payment/auth

HTTP

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

{
  "conversationId":"conversationId",
  "locale":"en",
  "paidPrice":1.0,
  "price":1.0,
  "paymentGroup":"PRODUCT",
  "currency":"TRY",
  "basketId":"B67832",
  "paymentChannel":"WEB",
  "installment": 1,
  "paymentCard":{
    "cardHolderName":"John Doe",
    "cardNumber":"5528790000000008",
    "expireMonth":"12",
    "expireYear":"2030",
    "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":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "city":"Istanbul",
    "country":"Turkey",
    "zipCode":"34732",
    "ip":"85.34.78.112"
  },
  "shippingAddress":{
    "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "zipCode":"34742",
    "contactName":"Jane Doe",
    "city":"Istanbul",
    "country":"Turkey"
  },
  "billingAddress":{
    "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "zipCode":"34742",
    "contactName":"Jane Doe",
    "city":"Istanbul",
    "country":"Turkey"
  },
  "basketItems":[
    {
      "id":"BI101",
      "price":0.3,
      "name":"Binocular",
      "category1":"Collectibles",
      "category2":"Accessories",
      "itemType":"PHYSICAL"
    }
  ]
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1700000000000,
  "conversationId": "conversationId",
  "price": 1,
  "paidPrice": 1,
  "installment": 1,
  "paymentId": "25147713",
  "fraudStatus": 1,
  "merchantCommissionRate": "0E-8",
  "merchantCommissionRateAmount": "0E-8",
  "iyziCommissionRateAmount": 0.0349,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "basketId": "B67832",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27137212",
      "transactionStatus": 2,
      "price": 0.3,
      "paidPrice": 0.3,
      "merchantCommissionRate": "0E-8",
      "merchantCommissionRateAmount": "0E-8",
      "iyziCommissionRateAmount": 0.01047,
      "iyziCommissionFee": 0.075,
      "blockageRate": "0E-8",
      "blockageRateAmountMerchant": "0E-8",
      "blockageRateAmountSubMerchant": "0E-8",
      "blockageResolvedDate": "2025-08-22 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": "0E-8",
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.21453,
      "convertedPayout": {
        "paidPrice": 0.3,
        "iyziCommissionRateAmount": 0.01047,
        "iyziCommissionFee": 0.075,
        "blockageRateAmountMerchant": "0E-8",
        "blockageRateAmountSubMerchant": "0E-8",
        "subMerchantPayoutAmount": "0E-8",
        "merchantPayoutAmount": 0.21453,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "579803",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "5ab609ed2e0f4cae0035c8c136d29b00c2616cf8fb4856df65bb52b5a796369f"
}

Sample Codes

PHP

Java

.Net

Node.Js

Python

Postman

Lastly analyzing following headlines, you can effectively handle and respond to the outcome of the payment inquiry, ensuring a smooth and reliable payment process for your customers.

• The status parameter provides information about the status of the transaction. success indicates that the transaction has been successfully completed and the payment has been processed. failure indicates that the transaction has failed, and an error message related to the failure reason is provided.

• The paymentStatus parameter is null for this service.

• The paymentId and paymentTransactionId values should be stored for future reference and tracking.

• In the event of a failed transaction (failure status), the errorCode, errorMessage, and errorGroup parameters will be returned with corresponding values, providing details about the error.