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

Responses

200

Successful response

application/json

Responseall of

400

Invalid request / validation error

application/json

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": "[email protected]",
  "card": {
    "cardAlias": "card_alias",
    "cardNumber": "5526080000000006",
    "expireYear": "2033",
    "expireMonth": "12",
    "cardHolderName": "john doe"
  }
}

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

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

Responseall of

400

Invalid request / validation error

application/json

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

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

400

Invalid request / validation error

application/json

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

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

Responseall of

400

Invalid request / validation error

application/json

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 protected]",
    "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

PreviousAdvanced NextReporting Service

Last updated 16 days ago