Ctrlk
GitHubFeedback Form
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

If you want to store the card during the payment process, simply send the registeredCard parameter as 1 in NON3D or 3DS payment requests.

Create User and Card

post

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.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

Media type of the request body.

Example: application/json
Body
or
Responses
200

Successful response

application/json

Standard response fields.

statusstring · enumOptional

It shows the result of the request.

Example: successPossible values:
localestring · enumOptional

Response language.

Example: enPossible values:
systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941
conversationIdstringOptional

If sent in the request, echoed back in the response for correlation.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total amount charged.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149157
fraudStatusinteger · enumOptional

Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.

  • 1: Approved.
  • 0: Under review — wait for notification.
  • -1: Rejected.
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s own installment/commission rate. If price=100 and paidPrice=110, the merchant rate is 10%. Informational.

Example: 10
merchantCommissionRateAmountdecimalOptional

Merchant’s own commission amount (e.g., 10 in the example above). Informational.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico commission rate amount.

Example: 0.03839
iyziCommissionFeedecimalOptional

iyzico transaction fee for the payment.

Example: 0.25
cardTypestring · enumOptional

Card type.

Example: CREDIT_CARDPossible values:
cardAssociationstring · enumOptional

Card association.

Example: MASTER_CARDPossible values:
cardFamilystring · enumOptional

Card family (returned for local cards).

Example: AxessPossible values:
binNumberstringOptional

First 8 digits of the card.

Example: 55260800
lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006
basketIdstringOptional

Basket ID.

Example: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Authorization code.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Bank-provided hostReference value for the payment.

Example: mock00007iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
externalIdstringOptional

The externalId value sent in the request.

Example: 665864cefa5eac24beba9ebb
emailstringOptional

Email on the stored card (may be returned only in the first variant).

Example: test@test.com
cardUserKeystringOptional

User key for the stored card. Used to charge again.

Example: d5616aac-84a4-9008-d4a7-0bc5ebc2ce68
cardTokenstringOptional

Token of the stored card. Used to charge again.

Example: 8fb4b2c0-3030-4a95-5fd6-a3049ca3bbd2
cardAliasstringOptional

Alias of the card.

Example: card alias
cardBankCodeintegerOptional

If the card is a local card, its bank code.

Example: 46
cardBankNamestringOptional

If the card is a local card, its bank name.

Example: Akbank
post/cardstorage/card
POST https://api.iyzipay.com/cardstorage/card
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "test@test.com",
  "card": {
    "cardAlias": "card_alias",
    "cardNumber": "5526080000000006",
    "expireYear": "2033",
    "expireMonth": "12",
    "cardHolderName": "john doe"
  }
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1756301363865,
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "test@test.com",
  "cardUserKey": "d5616aac-84a4-9008-d4a7-0bc5ebc2ce68",
  "cardToken": "8fb4b2c0-3030-4a95-5fd6-a3049ca3bbd2",
  "binNumber": "55260800",
  "lastFourDigits": "0006",
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "cardAlias": "card_alias",
  "cardBankCode": 46,
  "cardBankName": "Akbank"
}

Sample Codes

PHP

Java

.NET

Python

Node.js

Postman

List Stored Cards

post

You can list the cards that belong to a user in iyzico.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

Media type of the request body.

Example: application/json
Body

Request to list stored cards.

localestring · enumOptional

Response language. Default tr.

Example: enPossible values:
conversationIdstringOptional

Correlation ID sent for request/response matching.

Example: 23233333
cardUserKeystringRequired

User key whose cards will be listed.

Example: 6abd3f19-8305-d0c9-09e2-0300b5516a38
Responses
200

Successful response — Card list

application/json

Standard response fields.

statusstring · enumOptional

It shows the result of the request.

Example: successPossible values:
localestring · enumOptional

Response language.

Example: enPossible values:
systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941
conversationIdstringOptional

If sent in the request, echoed back in the response for correlation.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total amount charged.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149157
fraudStatusinteger · enumOptional

Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.

  • 1: Approved.
  • 0: Under review — wait for notification.
  • -1: Rejected.
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s own installment/commission rate. If price=100 and paidPrice=110, the merchant rate is 10%. Informational.

Example: 10
merchantCommissionRateAmountdecimalOptional

Merchant’s own commission amount (e.g., 10 in the example above). Informational.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico commission rate amount.

Example: 0.03839
iyziCommissionFeedecimalOptional

iyzico transaction fee for the payment.

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: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Authorization code.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Bank-provided hostReference value for the payment.

Example: mock00007iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
cardUserKeystringOptional

User key whose cards are listed.

Example: 7f4be1bd-1f46-3425-f2ea-3a9ecd70f182
post/cardstorage/cards
POST /cardstorage/cards HTTP/1.1
Host: api.iyzipay.com
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "locale": "en",
  "conversationId": "23233333",
  "cardUserKey": "6abd3f19-8305-d0c9-09e2-0300b5516a38"
}
{
  "status": "success",
  "locale": "en",
  "systemTime": 1756307234300,
  "conversationId": "23233333",
  "cardUserKey": "7f4be1bd-1f46-3425-f2ea-3a9ecd70f182",
  "cardDetails": [
    {
      "cardToken": "dc9f677b-d658-7458-0b7f-a0fccdb05019",
      "cardAlias": "card_alias",
      "binNumber": "55260800",
      "lastFourDigits": "0006",
      "cardType": "CREDIT_CARD",
      "cardAssociation": "MASTER_CARD",
      "cardFamily": "Axess",
      "cardBankCode": 46,
      "cardBankName": "Akbank",
      "expireMonth": "12",
      "expireYear": "2033"
    }
  ]
}

Sample Codes

PHP

Java

.NET

Python

Node.js

Postman

Delete a Stored Card

delete

Deletes a card that belongs to a user created in iyzico.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

Media type of the request body.

Example: application/json
Body

Request to delete a stored card.

localestring · enumOptional

Response language. Default tr.

Example: enPossible values:
conversationIdstringOptional

Correlation ID sent for request/response matching.

Example: 123456789
cardUserKeystringRequired

User key of the stored card.

Example: 6abd3f19-8305-d0c9-09e2-0300b5516a38
cardTokenstringRequired

Token of the card to be deleted.

Example: c80ba376-8250-f819-88c9-94984710e72c
Responses
200

Successful response

application/json

Standard response fields.

statusstring · enumOptional

It shows the result of the request.

Example: successPossible values:
localestring · enumOptional

Response language.

Example: enPossible values:
systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941
conversationIdstringOptional

If sent in the request, echoed back in the response for correlation.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total amount charged.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149157
fraudStatusinteger · enumOptional

Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.

  • 1: Approved.
  • 0: Under review — wait for notification.
  • -1: Rejected.
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s own installment/commission rate. If price=100 and paidPrice=110, the merchant rate is 10%. Informational.

Example: 10
merchantCommissionRateAmountdecimalOptional

Merchant’s own commission amount (e.g., 10 in the example above). Informational.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico commission rate amount.

Example: 0.03839
iyziCommissionFeedecimalOptional

iyzico transaction fee for the payment.

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: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Authorization code.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Bank-provided hostReference value for the payment.

Example: mock00007iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

Example: 03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182
delete/cardstorage/card
DELETE https://api.iyzipay.com/cardstorage/card
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "cardUserKey": "6abd3f19-8305-d0c9-09e2-0300b5516a38",
  "cardToken": "c80ba376-8250-f819-88c9-94984710e72c"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1756308913460,
  "conversationId": "123456789"
}

Sample Codes

PHP

Java

.NET

Python

Node.js

Postman

Crate Payment with Stored Card (NON3D)

post

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.

Header parameters
AuthorizationstringRequired

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

Content-TypestringRequired

Media type of the request body.

Example: application/json
Body

Request to NON3D payment using a stored card.

localestring · enumOptional

Language code. Default; tr

Example: enPossible values:
conversationIdstringOptional

Unique ID for request/response correlation.

Example: conversationId
paidPricedecimalRequired

Total amount to be charged from the customer.

Example: 1
pricedecimalRequired

Basket total amount.

Example: 1
installmentinteger · enumOptional

Installment count. If omitted, single installment (1) is used.

Example: 1Possible values:
paymentChannelstring · enumOptional

Payment channel.

Example: WEBPossible values:
basketIdstringOptional

Basket ID.

Example: B67832
paymentGroupstring · enumOptional

Payment group. Default; PRODUCT.

Example: PRODUCTPossible values:
currencystring · enumOptional

Currency. Default; TRY.

Example: TRYPossible values:
Responses
200

Successful response — payment captured

application/json

Standard response fields.

statusstring · enumOptional

It shows the result of the request.

Example: successPossible values:
localestring · enumOptional

Response language.

Example: enPossible values:
systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755198001941
conversationIdstringOptional

If sent in the request, echoed back in the response for correlation.

Example: conversationId
pricedecimalOptional

Basket total amount.

Example: 1
paidPricedecimalOptional

Total amount charged.

Example: 1
installmentintegerOptional

Installment count.

Example: 1
paymentIdstringOptional

Payment ID.

Example: 25149157
fraudStatusinteger · enumOptional

Payment status based on fraud filters. If the fraud risk score is low, the payment is approved immediately; if high, it is rejected.

  • 1: Approved.
  • 0: Under review — wait for notification.
  • -1: Rejected.
Example: 1Possible values:
merchantCommissionRatedecimalOptional

Merchant’s own installment/commission rate. If price=100 and paidPrice=110, the merchant rate is 10%. Informational.

Example: 10
merchantCommissionRateAmountdecimalOptional

Merchant’s own commission amount (e.g., 10 in the example above). Informational.

Example: 0.1
iyziCommissionRateAmountdecimalOptional

iyzico commission rate amount.

Example: 0.03839
iyziCommissionFeedecimalOptional

iyzico transaction fee for the payment.

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: B67832
currencystring · enumOptionalExample: TRYPossible values:
authCodestringOptional

Authorization code.

Example: 526832
phasestringOptionalExample: AUTH
hostReferencestringOptional

Bank-provided hostReference value for the payment.

Example: mock00007iyzihostrfn
signaturestringOptional

Signature value that can be used for verification.

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

{
  "locale": "en",
  "conversationId": "123456789",
  "price": 1.0,
  "paidPrice": 1.1,
  "installment": 1,
  "paymentChannel": "WEB",
  "basketId": "B67832",
  "paymentGroup": "LISTING",
  "currency": "TRY",
  "paymentCard": {
    "cardUserKey": "7f4be1bd-1f46-3425-f2ea-3a9ecd70f182",
    "cardToken": "dc9f677b-d658-7458-0b7f-a0fccdb05019"
  },
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "74300864791",
    "email": "email@email.com",
    "gsmNumber": "+905350000000",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "basketItems": [
    {
      "id": "BI101",
      "price": 1,
      "name": "Binocular",
      "category1": "Collectibles",
      "category2": "Accessories",
      "itemType": "PHYSICAL"
    }
  ]
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1756309795470,
  "conversationId": "123456789",
  "price": 1,
  "paidPrice": 1.1,
  "installment": 1,
  "paymentId": "25232429",
  "fraudStatus": 1,
  "merchantCommissionRate": 10,
  "merchantCommissionRateAmount": 0.1,
  "iyziCommissionRateAmount": 0.03839,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "B67832",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "27221602",
      "transactionStatus": 2,
      "price": 1,
      "paidPrice": 1.1,
      "merchantCommissionRate": 10,
      "merchantCommissionRateAmount": 0.1,
      "iyziCommissionRateAmount": 0.03839,
      "iyziCommissionFee": 0.25,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-09-03 18:49:55",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.81161,
      "convertedPayout": {
        "paidPrice": 1.1,
        "iyziCommissionRateAmount": 0.03839,
        "iyziCommissionFee": 0.25,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.81161,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "526832",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "03d01d123540295e0658e6400f096fbd346791df3838e6644740121db937e182"
}

Sample Codes

PHP

Java

.NET

Python

Node.js

Postman

PreviousAdvanced
NextReporting Service

Last updated