# 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
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.iyzico.com/en/advanced/card-storage.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.