Card Storage

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: [email protected]

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": "[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"
}

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"
    }
  ]
}

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"
}

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": "[email protected]",
    "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"
}