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

application/json

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: [e-mail]

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

400

Invalid request / validation error

application/json

post

/cardstorage/card

HTTP — New usercURL — New userHTTP — Existing usercURL — Existing user

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

{
  "locale": "en",
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "[e-mail]",
  "card": {
    "cardAlias": "card_alias",
    "cardNumber": "5526080000000006",
    "expireYear": "2033",
    "expireMonth": "12",
    "cardHolderName": "john doe"
  }
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1756301363865,
  "conversationId": "conversationId",
  "externalId": "665864cefa5eac24beba9ebb",
  "email": "[e-mail]",
  "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

application/json

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

400

Invalid request / validation error

application/json

post

/cardstorage/cards

HTTPcURLJavaScriptPython

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

application/json

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

400

Invalid request / validation error

application/json

delete

/cardstorage/card

HTTPcURL

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

application/json

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

400

Invalid request / validation error

application/json

post

/payment/auth

HTTP — NON3DcURL — NON3D

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": "[e-mail]",
    "gsmNumber": "[phone]",
    "registrationDate": "2013-04-21 15:12:09",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationAddress": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "85.34.78.112"
  },
  "shippingAddress": {
    "address": "Altunizade Mah. İnci Çıkmazı Sokak No: 3 İç Kapı No: 10 Üsküdar İstanbul",
    "zipCode": "34742",
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey"
  },
  "billingAddress": {
    "address": "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