# Card Storage Card storage feature provides a secure and convenient solution for managing payment card information, allowing users to securely save and manage card details for future transactions. {% hint style="info" %} If you want to store the card during the payment process, simply send the `registeredCard` parameter as `1` in NON3D or 3DS payment requests. {% endhint %} ## Create User and Card > You can create a \*\*user\*\* and a \*\*card\*\* linked to that user in iyzico without creating a payment. Or, using the same endpoint, you can \*\*add a new card\*\* to an \*\*existing user\*\*. Request parameters differ between the two variants. Both request bodies and JSON examples are provided below. ```json {"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/card":{"post":{"summary":"Create User and Card","description":"You can create a **user** and a **card** linked to that user in iyzico without creating a payment. Or, using the same endpoint, you can **add a new card** to an **existing user**. Request parameters differ between the two variants. Both request bodies and JSON examples are provided below.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CardCreateRequest"},{"$ref":"#/components/schemas/CardCreateWithUserKeyRequest"}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardCreateSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardCreateRequest":{"type":"object","description":"Create a user and a card (new user + first card).","properties":{"locale":{"type":"string","description":"Sets the language of messages returned by iyzico. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Value you send to correlate request/response."},"externalId":{"type":"string","description":"ID assigned by the merchant to the card to be stored."},"email":{"type":"string","description":"Email of the stored card owner."},"card":{"$ref":"#/components/schemas/Card"}},"required":["email","card"]},"Card":{"type":"object","description":"Card information.","properties":{"cardAlias":{"type":"string","description":"The name assigned to the stored card. It is defined by the merchant and can be used to match it with your system."},"expireYear":{"type":"string","description":"Expiration year on the card."},"expireMonth":{"type":"string","description":"Expiration month on the card."},"cardNumber":{"type":"string","description":"Card number."},"cardHolderName":{"type":"string","description":"Name printed on the card."}},"required":["cardNumber","expireYear","expireMonth","cardHolderName"]},"CardCreateWithUserKeyRequest":{"type":"object","description":"Add a second/additional card to an existing user.","properties":{"locale":{"type":"string","description":"Sets the language of messages returned by iyzico. Default is `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation (optional)."},"cardUserKey":{"type":"string","description":"Existing user key to which the card will be added."},"card":{"$ref":"#/components/schemas/Card"}},"required":["cardUserKey","card"]},"CardCreateSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"externalId":{"type":"string","description":"The `externalId` value sent in the request."},"email":{"type":"string","description":"Email on the stored card (may be returned only in the first variant)."},"cardUserKey":{"type":"string","description":"User key for the stored card. Used to charge again."},"cardToken":{"type":"string","description":"Token of the stored card. Used to charge again."},"binNumber":{"type":"string","description":"First 8 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family (returned for local cards).","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"cardAlias":{"type":"string","description":"Alias of the card."},"cardBankCode":{"type":"integer","description":"If the card is a local card, its bank code."},"cardBankName":{"type":"string","description":"If the card is a local card, its bank name."}}}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}} ``` #### Sample Codes
PHP
Java
.NET
Python
Node.js
Postman
## List Stored Cards > You can list the cards that belong to a user in iyzico. ```json {"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/cards":{"post":{"summary":"List Stored Cards","description":"You can list the cards that belong to a user in iyzico.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListRequest"}}}},"responses":{"200":{"description":"Successful response — Card list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardListRequest":{"type":"object","description":"Request to list stored cards.","properties":{"locale":{"type":"string","description":"Response language. Default `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Correlation ID sent for request/response matching."},"cardUserKey":{"type":"string","description":"User key whose cards will be listed."}},"required":["cardUserKey"]},"CardListSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"cardUserKey":{"type":"string","description":"User key whose cards are listed."},"cardDetails":{"type":"array","description":"List of stored cards for the user.","items":{"$ref":"#/components/schemas/CardListItem"}}}}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"CardListItem":{"type":"object","description":"Stored card information.","properties":{"cardToken":{"type":"string","description":"Stored card token."},"cardAlias":{"type":"string","description":"Alias for the card."},"binNumber":{"type":"string","description":"First 6 or 8 digits of the card."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family (for local cards).","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"cardBankCode":{"type":"integer","description":"Bank code (for local cards)."},"cardBankName":{"type":"string","description":"Bank name (for local cards)."},"expireMonth":{"type":"string","description":"Expire month."},"expireYear":{"type":"string","description":"Expire year."}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}} ``` #### Sample Codes
PHP
Java
.NET
Python
Node.js
Postman
## Delete a Stored Card > Deletes a card that belongs to a user created in iyzico. ```json {"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/cardstorage/card":{"delete":{"summary":"Delete a Stored Card","description":"Deletes a card that belongs to a user created in iyzico.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDeleteRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"CardDeleteRequest":{"type":"object","description":"Request to delete a stored card.","properties":{"locale":{"type":"string","description":"Response language. Default `tr`.","enum":["tr","en"]},"conversationId":{"type":"string","description":"Correlation ID sent for request/response matching."},"cardUserKey":{"type":"string","description":"User key of the stored card."},"cardToken":{"type":"string","description":"Token of the card to be deleted."}},"required":["cardUserKey","cardToken"]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}} ``` #### Sample Codes
PHP
Java
.NET
Python
Node.js
Postman
## Crate Payment with Stored Card (NON3D) > After card storage, you can send a “NON3D or 3DS” payment request using the returned \`cardUserKey\` and \`cardToken\`. Unlike a standard payment request, card details are sent via \`cardUserKey\` and \`cardToken\`. Suitable for one-click payments or subscription cycles. Example below shows NON3D. ```json {"openapi":"3.0.3","info":{"title":"Card Storage — Create User & Card","version":"1.1.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/payment/auth":{"post":{"summary":"Crate Payment with Stored Card (NON3D)","description":"After card storage, you can send a “NON3D or 3DS” payment request using the returned `cardUserKey` and `cardToken`. Unlike a standard payment request, card details are sent via `cardUserKey` and `cardToken`. Suitable for one-click payments or subscription cycles. Example below shows NON3D.","tags":["Card Storage"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAuthSavedCardRequest"}}}},"responses":{"200":{"description":"Successful response — payment captured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAuthSuccessResponse"}}}},"400":{"description":"Invalid request / validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Media type of the request body."}},"schemas":{"PaymentAuthSavedCardRequest":{"type":"object","description":"Request to NON3D payment using a stored card.","properties":{"locale":{"type":"string","description":"Language code. Default; tr","enum":["tr","en"]},"conversationId":{"type":"string","description":"Unique ID for request/response correlation."},"paidPrice":{"type":"decimal","description":"Total amount to be charged from the customer."},"price":{"type":"decimal","description":"Basket total amount."},"installment":{"type":"integer","description":"Installment count. If omitted, single installment (1) is used.","enum":[1,2,3,6,9,12]},"paymentChannel":{"type":"string","description":"Payment channel.","enum":["WEB","MOBILE","MOBILE_WEB","MOBILE_IOS","MOBILE_ANDROID","MOBILE_WINDOWS","MOBILE_TABLET","MOBILE_PHONE"]},"basketId":{"type":"string","description":"Basket ID."},"paymentGroup":{"type":"string","description":"Payment group. Default; PRODUCT.","enum":["PRODUCT","LISTING","SUBSCRIPTION"]},"currency":{"type":"string","description":"Currency. Default; TRY.","enum":["TRY","USD","EUR","GBP","NOK","CHF"]},"paymentCard":{"$ref":"#/components/schemas/PaymentCardSaved"},"buyer":{"description":"Buyer information.","$ref":"#/components/schemas/Buyer"},"shippingAddress":{"description":"Shipping Address. Required if at least one basket item is `PHYSICAL`. Not required if all items are `VIRTUAL`.","$ref":"#/components/schemas/Address"},"billingAddress":{"description":"Billing Address.","$ref":"#/components/schemas/Address"},"basketItems":{"description":"Basket items.","type":"array","items":{"$ref":"#/components/schemas/BasketItem"}}},"required":["price","paidPrice","paymentCard","buyer","shippingAddress","billingAddress","basketItems"]},"PaymentCardSaved":{"type":"object","description":"Token data for the card.","properties":{"cardUserKey":{"type":"string","description":"cardUserKey returned by iyzico after card storage."},"cardToken":{"type":"string","description":"cardToken returned by iyzico for the stored card."}},"required":["cardUserKey","cardToken"]},"Buyer":{"type":"object","required":["id","name","surname","identityNumber","email","gsmNumber","registrationAddress","city","country"],"properties":{"id":{"type":"string","description":"Buyer ID."},"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"identityNumber":{"type":"string","description":"National ID number (Türkiye)."},"email":{"type":"string","description":"Email."},"gsmNumber":{"type":"string","description":"Phone number."},"registrationDate":{"type":"string","description":"Registration date (yyyy-MM-dd HH:mm:ss)."},"lastLoginDate":{"type":"string","description":"Last login date (yyyy-MM-dd HH:mm:ss)."},"registrationAddress":{"type":"string","description":"Address."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."},"zipCode":{"type":"string","description":"Zip / postal code."},"ip":{"type":"string","description":"IP address."}}},"Address":{"type":"object","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Full address."},"zipCode":{"type":"string","description":"Zip / postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"BasketItem":{"type":"object","required":["id","price","name","category1","itemType"],"properties":{"id":{"type":"string","description":"Product ID."},"price":{"type":"decimal","description":"Product price."},"name":{"type":"string","description":"Product name."},"category1":{"type":"string","description":"Primary category."},"category2":{"type":"string","description":"Secondary category (optional)."},"itemType":{"type":"string","description":"Item type.","enum":["PHYSICAL","VIRTUAL"]},"subMerchantKey":{"type":"string","description":"Sub-merchant key for the service provider. Not used in the standard business model; required only for marketplace model."},"subMerchantPrice":{"type":"decimal","description":"Amount to be transferred to the sub-merchant. Not used in the standard business model; required only for marketplace model."}}},"PaymentAuthSuccessResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]},"BaseResponse":{"type":"object","description":"Standard response fields.","properties":{"status":{"type":"string","description":"It shows the result of the request.","enum":["success","failure"]},"locale":{"type":"string","description":"Response language.","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"If sent in the request, echoed back in the response for correlation."},"price":{"type":"decimal","description":"Basket total amount."},"paidPrice":{"type":"decimal","description":"Total amount charged."},"installment":{"type":"integer","description":"Installment count."},"paymentId":{"type":"string","description":"Payment ID."},"fraudStatus":{"type":"integer","description":"Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.\n- **1**: Approved.\n- **0**: Under review — wait for notification.\n- **-1**: Rejected.\n","enum":[0,-1,1]},"merchantCommissionRate":{"type":"decimal","description":"Merchant’s own installment/commission rate. If `price=100` and `paidPrice=110`, the merchant rate is 10%. Informational."},"merchantCommissionRateAmount":{"type":"decimal","description":"Merchant’s own commission amount (e.g., 10 in the example above). Informational."},"iyziCommissionRateAmount":{"type":"decimal","description":"iyzico commission rate amount."},"iyziCommissionFee":{"type":"decimal","description":"iyzico transaction fee for the payment."},"cardType":{"type":"string","description":"Card type.","enum":["CREDIT_CARD","DEBIT_CARD","PREPAID_CARD"]},"cardAssociation":{"type":"string","description":"Card association.","enum":["VISA","MASTER_CARD","AMERICAN_EXPRESS"]},"cardFamily":{"type":"string","description":"Card family.","enum":["Bonus","Axess","World","Maximum","Paraf","Enpara Bank DC","QNB CC","QNB DC","Ziraat Bankası DC","BankkartCombo","Albaraka Türk DC","Vakıfbank DC","Neo","Paracard","TEB DC","Kuveyt Türk CC","Kuveyt Türk DC","Shop&Fly","Halkbank DC","Papara Card","Tlcard","Tosla","Bankamatik","ING Bank DC","Sipay DC","T.O.M.Kt.Bnk.A.Ş. CC","Turk Telekom","PTT DC","Miles&Smiles","Denizbank DC"]},"binNumber":{"type":"string","description":"BIN (first 8 digits)."},"lastFourDigits":{"type":"string","description":"Last 4 digits of the card."},"basketId":{"type":"string","description":"Basket ID."},"currency":{"type":"string","enum":["TRY","USD","EUR","NOK","CHF","GBP"]},"itemTransactions":{"type":"array","items":{"$ref":"#/components/schemas/ItemTransaction"}},"authCode":{"type":"string","description":"Authorization code."},"phase":{"type":"string"},"hostReference":{"type":"string","description":"Bank-provided hostReference value for the payment."},"signature":{"type":"string","description":"Signature value that can be used for verification."}}},"ItemTransaction":{"type":"object","description":"Line items for basket transactions.","properties":{"itemId":{"type":"string","description":"Merchant-provided ID for the basket item."},"paymentTransactionId":{"type":"string","description":"ID of the payment breakdown; must be stored by the merchant (used for refund/capture/approval and communication with iyzico)."},"transactionStatus":{"type":"integer","description":"Status of the payment breakdown.\n- **0**: Under fraud review\n- **-1**: Rejected after fraud review\n- **1**: Approved (In marketplace, 1 means \"Awaiting Merchant Approval\")\n- **2**: Approved (Marketplace approval given)\n","enum":[0,-1,1,2]},"price":{"type":"decimal","description":"Item amount on the merchant side."},"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"installment":{"type":"integer","description":"Installment count."},"blockageRate":{"type":"decimal","description":"Merchant blockage rate for the line. Per agreement, iyzico may apply blockage to mitigate fraud risk."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountsubMerchant":{"type":"decimal","description":"Blockage amount for the sub-merchant on this line."},"blockageResolvedDate":{"type":"string","description":"Blockage release date for the transaction. Format; yyyy-MM-dd HH:mm:ss (e.g., 2015-10-19 14:36:52).","enum":["2015-10-19 14:36:52"]},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"merchantCommissionRate":{"type":"decimal","description":"Distributed merchant commission rate for this line."},"merchantCommissionRateAmount":{"type":"decimal","description":"Distributed merchant commission amount for this line."},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"subMerchantPrice":{"type":"decimal","description":"Sub-merchant entitlement."},"subMerchantPayoutRate":{"type":"string","description":"Sub-merchant payout rate."},"subMerchantPayoutAmount":{"type":"decimal","description":"Amount to be transferred to the sub-merchant."},"convertedPayout":{"$ref":"#/components/schemas/ConvertedPayout"}}},"ConvertedPayout":{"type":"object","description":"Post-conversion calculations per line item.","properties":{"paidPrice":{"type":"decimal","description":"Distribution of the collected amount for this line. Must be stored by the merchant."},"iyziCommissionFee":{"type":"decimal","description":"Distributed iyzico transaction fee for this line."},"iyziCommissionRateAmount":{"type":"decimal","description":"Distributed iyzico commission amount for this line."},"blockageRateAmountMerchant":{"type":"decimal","description":"Portion of the blockage amount reflected to the merchant for this line."},"blockageRateAmountSubMerchant":{"type":"string"},"subMerchantPayoutAmount":{"type":"string"},"merchantPayoutAmount":{"type":"decimal","description":"Amount to be sent to the merchant after fees/commissions/blockages."},"iyziConversationRate":{"type":"decimal","description":"Conversion rate."},"iyziConversationRateAmount":{"type":"decimal","description":"Amount after applying the conversion rate."},"currency":{"type":"string","enum":["TRY","USD","EUR","GBP","NOK","CHF"]}}},"ErrorResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"errorCode":{"type":"string","description":"Code describing the error, if any."},"errorMessage":{"type":"string","description":"Localized error message (depends on the `locale`)."},"errorGroup":{"type":"string","description":"Error category/group."}}}]}}}} ``` #### Sample Codes
PHP
Java
.NET
Python
Node.js
Postman