Subscription Transactions

The services included in the subscription transactions are listed below.

1. Initialize Subscription

2. Activate Subscription

3. Retry Subscription Payment

4. Upgrade Subscription

5. Cancel Subscription

6. Get Subscription Details

7. Search Subcriptions

8. Subscription Card Update

Initialize Subscription

If you have completed all the steps, you can now start the subscription process.

Subscription can be started in 2 different ways.

1. Checkout Form

2. NON-3DS

Both methods above give the same result, but there is a difference in the way they are used.

The subscription process always starts with an ACTIVE or PENDING status. If the status is PENDING or the status is ACTIVE but a trial period is specified in the payment plan, iyzico only validates the card in the subscription request. Card validation takes place with a 1 TL withdrawal and subsequent refund. Apart from this, no transaction or payment takes place.

If the subscription status is ACTIVE and no trial period is specified in the planning, the payment specified in the plan is taken from the card and the subscription is started.

Each subscription requires a card information. Your customers can start a subscription with the cards they have stored in the iyzico environment or with a new card. When requesting a card update, the subscriptionReferenceCode of the relevant subscription must be sent. In this case, only the card information of the relevant subscription will be updated.

Table of Subscription Status

DURUMU	AÇIKLAMA
ACTIVE	Bir abonelik aktif ise ve ödemeler düzenli olarak alınıyorsa status active olur.
PENDING	Bir abonelik durdurulmuşsa status pending olur.
UNPAID	Abonelik sırasında ödeme alınamamış ise status unpaid olur.
UPGRADED	Abonelik başka bir plan ile güncellenmişse status upgraded olur.
CANCELED	Abonelik iptal edilmişse status cancelled olur.
EXPIRED	Abonelik periyodu bitmişse status expired olur. Karttan başka bir ödeme alınmaz.

Initializing Subscription via Checkout Form

To create a checkout form, merchants must submit the following information.

• Payment Plan Reference Code

• Customer information

• Subscription Status

• CallBackURL (the address where the Checkout Form result will be posted)

CallBackUrl is given by member merchants during the request and determines the page to which the end user will be directed after payment. Redirection occurs as soon as the customer makes the payment. At this point, the payment request was sent to the bank and the result was processed by iyzico. The member business must check whether the payment has been received with a separate request. If the card validation or first payment is successful, all other processes are carried out by iyzico.

If your customer has a card stored in the iyzico environment, the option to pay with a stored card will appear on the checkout form. In this case, our member businesses do not need to send an additional request.

Via iyzico Checkout Form, an htmlContent parameter is returned as a result of the form creation request. When this javascript code snippet is printed on the page, the iyzico library is ready to be loaded into any of the “divs” mentioned below. The checkout form will appear when the page is completely loaded.

The divs where the checkout form will be loaded can be responsive or popup. Examples are given below.

<div id="iyzipay-checkout-form" class="responsive"></div>

<div id="iyzipay-checkout-form" class="popup"></div>

Initialize Subscription (iyzico Checkout Form)

post

Used to start a subscription with iyzico Checkout Form. Returns the form content and token.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

The request content type.

Example: application/json

Body

application/json

localestring · enumOptional

Language code. Default is tr. Send "en" to create the checkout form in English.

Example: enPossible values:

callbackUrlstringRequired

Callback URL to which the payment result will be sent.

Example: https://callbackUrl.com

pricingPlanReferenceCodestringRequired

Reference code of the plan to start the subscription.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

subscriptionInitialStatusstring · enumRequired

Initial status. If PENDING, subscription will not start until activated.

Example: ACTIVEPossible values:

conversationIdstringOptional

Optional correlation value to match request/response pairs.

Example: 123456789

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/checkoutform/initialize

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/checkoutform/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "callbackUrl": "https://callbackUrl.com",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "subscriptionInitialStatus": "ACTIVE",
  "conversationId": "conversationId",
  "customer": {
    "name": "John",
    "surname": "Stone",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "identityNumber": "1234567890",
    "billingAddress": {
      "address": "Altunizade Mah. Inci Cikmazi Sokak No: 3, Uskudar Istanbul",
      "zipCode": "34345",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Turkey"
    },
    "shippingAddress": {
      "address": "Altunizade Mah. Inci Cikmazi Sokak No: 3, Uskudar Istanbul",
      "zipCode": "34345",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Turkey"
    }
  }
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755596201712,
  "conversationId": "conversationId",
  "token": "a9f91f36-2110-4c55-848e-bdd2c7016171",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"a9f91f36-2110-4c55-848e-bdd2c7016171\",price:1.00,...}};</script>",
  "tokenExpireTime": 1800
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Initialize Subscription (NON3D)

post

Start a subscription without the hosted checkout form, using your own payment form via NON3D service.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

The request content type.

Example: application/json

Body

application/json

pricingPlanReferenceCodestringRequired

Reference code of the plan to start the subscription.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

conversationIdstringOptional

Optional correlation value to match request/response pairs.

Example: 123456789

subscriptionInitialStatusstring · enumRequired

Initial status. If PENDING, subscription will not start until activated.

Example: ACTIVEPossible values:

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/initialize

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "conversationId": "conv-1001",
  "subscriptionInitialStatus": "ACTIVE",
  "customer": {
    "name": "John",
    "surname": "Stone",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "identityNumber": "1234567890",
    "billingAddress": {
      "address": "Altunizade Mah. Inci Cikmazi Sokak No: 3, Uskudar Istanbul",
      "contactName": "contactName",
      "city": "Istanbul",
      "country": "Turkey"
    },
    "shippingAddress": {
      "address": "address",
      "zipCode": "zipCode",
      "contactName": "contactName",
      "city": "city",
      "country": "country"
    }
  },
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5528790000000008",
    "expireMonth": "12",
    "expireYear": "2030",
    "cvc": "123"
  }
}

{
  "status": "success",
  "systemTime": 1755598000000,
  "data": {
    "referenceCode": "8d06cc19-98fb-47a6-ae1f-47f20c4797b4",
    "parentReferenceCode": "535094d2-9257-401b-8e38-f08308e37098",
    "pricingPlanReferenceCode": "515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "775ba402-41f0-4674-968b-43cc787d9366",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755599766595,
    "trialEndDate": 1756031766595,
    "createdDate": 1755599766595,
    "startDate": 1755599766595,
    "endDate": 1787567766595
  }
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Retrieve Checkout Form Result

get

After the checkout form flow completes, query the subscription creation result with the returned token.

Path parameters

tokenstringRequired

Token returned by checkout form initialize for this operation.

Query parameters

conversationIdstringOptional

Optional correlation value you send in the request to match with the response.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

The request content type.

Example: application/json

Responses

200

Successful response

application/json

400

Error response

application/json

get

/v2/subscription/checkoutform/{token}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/checkoutform/1590292b-bed2-4909-8833-6c6f85d7ec17
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755597000000,
  "token": "a9f91f36-2110-4c55-848e-bdd2c7016171",
  "data": {
    "referenceCode": "8d06cc19-98fb-47a6-ae1f-47f20c4797b4",
    "parentReferenceCode": "535094d2-9257-401b-8e38-f08308e37098",
    "pricingPlanReferenceCode": "515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "775ba402-41f0-4674-968b-43cc787d9366",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755599766595,
    "trialEndDate": 1756031766595,
    "createdDate": 1755599766595,
    "startDate": 1755599766595,
    "endDate": 1787567766595
  }
}

Sample Codes

PHP

Java

Node.js

Postman

Initialize Subscription (Existing Customer)

post

If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

The request content type.

Example: application/json

Body

application/json

subscriptionInitialStatusstring · enumRequired

Initial status. If PENDING, subscription will not start until activated.

Example: ACTIVEPossible values:

pricingPlanReferenceCodestringRequired

Reference code of the plan to start the subscription.

Example: 7515f763-5da3-4a35-8f7f-d425ae44ac04

customerReferenceCodestringRequired

Reference code of the existing customer. Must already have an active subscription to start a new one with this flow.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/initialize/with-customer

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/initialize/with-customer
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "subscriptionInitialStatus": "ACTIVE",
  "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
  "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d"
}

{
  "status": "success",
  "systemTime": 1755606762264,
  "data": {
    "referenceCode": "009dac1a-00dc-41e8-a92f-2c24b18e27b9",
    "parentReferenceCode": "f4bb665b-a48a-4100-917f-d7a46b16e586",
    "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
    "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 5,
    "trialStartDate": 1755606762238,
    "trialEndDate": 1756038762238,
    "createdDate": 1755606762238,
    "startDate": 1755606762238,
    "endDate": 1787574762238
  }
}

Sample Codes

PHP

Java

Node.js

Postman

Activate Subscription

post

A subscription that was started as pending can be activated via this service.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription that was started as pending.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Header parameters

AuthorizationstringRequired

Authorization header; a Base64-encoded signed hash value that begins with IYZWSv2.

Content-TypestringRequired

Request body content type.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Reference code of the subscription that was started as pending.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/activate
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Retry Subscription Payment

post

If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

referenceCodestringRequired

Reference code of the failed payment. This is the orderReferenceCode value provided in the webhook notification for the failed subscription payment.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/operation/retry

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/operation/retry
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Cancel Subscription

post

Cancels an active subscription.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to cancel.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Subscription reference code. Can optionally be sent in the request body.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/cancel
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "subscriptionReferenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

{
  "status": "success",
  "systemTime": 1687096973255
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Upgrade Subscription

post

You can change or upgrade the plan during the subscription, provided that the new plan belongs to the same product and the billing interval (paymentInterval and paymentIntervalCount) remains the same. Use this service for price changes.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to upgrade.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

upgradePeriodstring · enumRequired

When the upgrade will take effect. Values:

• NOW: Apply the change immediately.
• NEXT_PERIOD: Apply the change at the next billing period.

Example: NOWPossible values:

newPricingPlanReferenceCodestringRequired

Reference code of the target pricing plan.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

useTrialbooleanOptional

If true, includes the trial period of the upgraded plan.

Example: false

resetRecurrenceCountbooleanOptional

• true: Recalculates the subscription end date according to the new plan’s recurrenceCount.
• false: Keeps the current plan’s end date and transfers it to the new plan.

Example: true

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/97fb885d-69e3-49ac-8590-9d05c9c6016e/upgrade
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "newPricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
  "upgradePeriod": "NEXT_PERIOD",
  "useTrial": false,
  "resetRecurrenceCount": true
}

{
  "status": "success",
  "systemTime": 1755613834401,
  "data": {
    "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
    "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
    "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
    "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 0,
    "createdDate": 1755613834375,
    "startDate": 1756045826566,
    "endDate": 1787581826566
  }
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Get Subscription Detail

get

Returns full details of a subscription by its reference code.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to query.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Subscription reference code. Can optionally be sent in the request body.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Responses

200

Successful response

application/json

get

/v2/subscription/subscriptions/{subscriptionReferenceCode}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/subscriptions/732a16cc-2ec4-4399-9aab-656cb6f5249e
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

200

Successful response

{
  "status": "success",
  "systemTime": 1755617091761,
  "data": {
    "totalCount": 1,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "732a16cc-2ec4-4399-9aab-656cb6f5249e",
        "parentReferenceCode": "aa86bbf7-176f-432e-8523-7c24cc250af4",
        "pricingPlanName": "Payment Plan V2 TEST",
        "pricingPlanReferenceCode": "deadd767-7d0a-4ddb-96f2-565ad245773d",
        "productName": "test",
        "productReferenceCode": "40070483-1a6e-4641-99c0-be513edcf9f2",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "ce88a44d-a4f5-4de9-8bbb-1f170a9be219",
        "subscriptionStatus": "UNPAID",
        "trialDays": 0,
        "createdDate": 1753186413089,
        "startDate": 1753186413089,
        "endDate": 1753229613089,
        "orders": [
          {
            "referenceCode": "684279ad-5caa-40a0-ae9a-95ec097d696d",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753190013089,
            "endPeriod": 1753193613089,
            "orderStatus": "WAITING",
            "paymentAttempts": [
              {
                "conversationId": "90cf2fdc-bb9a-4931-be32-f65312eb379d",
                "createdDate": 1753190040185,
                "paymentStatus": "FAILED",
                "errorCode": "5034",
                "errorMessage": "buyerSurname is required"
              }
            ]
          },
          {
            "referenceCode": "0759e5ce-1668-40cb-9570-d0b6eda8d988",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753186413089,
            "endPeriod": 1753190013089,
            "orderStatus": "SUCCESS",
            "paymentAttempts": [
              {
                "conversationId": "123456789",
                "createdDate": 1753186413090,
                "paymentId": 24578296,
                "paymentStatus": "SUCCESS"
              }
            ]
          }
        ]
      }
    ]
  }
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Search Subscriptions

get

Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only subscriptionStatus, you can list subscriptions with that status.

Path parameters

subscriptionReferenceCodestringOptional

Reference code of the subscription to query.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

customerReferenceCodestringOptional

Customer reference code.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

pricingPlanReferenceCodestringOptional

Reference code of the pricing plan used in the subscription.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

parentstringOptional

Parent reference code used for matching in subscription updates.

Example: 670489f2-9224-4a71-af6c-7044d22f5d73

subscriptionStatusstring · enumOptional

Subscription status filter.

Example: ACTIVEPossible values:

startDateintegerOptional

Subscription start date.

Example: 2025-08-24 14:30:26

endDateintegerOptional

Subscription end date (epoch ms).

Example: 2025-08-24 14:30:26

pageintegerOptional

Page number.

Example: 1

countintegerOptional

Number of records per page.

Example: 20

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Responses

200

Successful response

application/json

404

Example response for a wrong endpoint (e.g., typo).

application/json

get

/v2/subscription/subscriptions

HTTPcURL (multiple filters)

GET https://api.iyzipay.com/v2/subscription/subscriptions?startDate=2025-08-24 14:30:26&endDate=2026-08-24 14:30:26&subscriptionStatus=ACTIVE 
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755683471024,
  "data": {
    "totalCount": 4,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
        "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613834375,
        "startDate": 1756045826566,
        "endDate": 1787581826566,
        "orders": [
          {
            "referenceCode": "0ad2563a-f5b7-4a6c-b6ec-9dc7548493ec",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045826566,
            "endPeriod": 1758724226566,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "52c732ba-b449-460b-b553-ab21f9074300",
        "parentReferenceCode": "670489f2-9224-4a71-af6c-7044d22f5d73",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613786569,
        "startDate": 1756045757180,
        "endDate": 1787581757180,
        "orders": [
          {
            "referenceCode": "9723fa25-0968-4677-bd9a-559389252b58",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045757180,
            "endPeriod": 1758724157180,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "d5044ccc-f346-4a8c-81e7-272516a330a9",
        "parentReferenceCode": "6f0d463e-9a32-47ea-9a17-53d283f7f6ba",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613607741,
        "startDate": 1756045126208,
        "endDate": 1787581126208,
        "orders": [
          {
            "referenceCode": "e8c6d7f2-556d-4976-a44f-82e7f5b533c0",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045126208,
            "endPeriod": 1758723526208,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "5e4b1ec2-b0c0-47bf-b1bf-8656355cb82d",
        "parentReferenceCode": "7a67a645-3d81-4207-bab4-76beade2f6be",
        "pricingPlanName": "Current Plan",
        "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 5,
        "trialStartDate": 1755609729652,
        "trialEndDate": 1756041729652,
        "createdDate": 1755609702703,
        "startDate": 1755609729652,
        "orders": [
          {
            "referenceCode": "664a7e09-8ca2-45d8-9996-b340a94d90cb",
            "price": 99.99,
            "currencyCode": "TRY",
            "startPeriod": 1756041729652,
            "endPeriod": 1758720129652,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      }
    ]
  }
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Subscription Card Update (Checkout Form)

post

Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. The update can only be performed through the iyzico Checkout Form. A ₺1 validation charge is taken and immediately refunded to validate the updated card.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

callbackUrlstringRequired

Callback URL where the update result will be posted.

Example: https://www.merchant.com/callback

customerReferenceCodestringRequired

Reference code of the customer whose card will be updated.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

subscriptionReferenceCodestringOptional

If updating on a specific subscription, the subscription reference code (optional).

Example: 52c732ba-b449-460b-b553-ab21f9074300

localestring · enumOptional

Response language preference.

Example: enPossible values:

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/card-update/checkoutform/initialize

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/card-update/checkoutform/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "callbackUrl": "https://www.merchant.com/callback",
  "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
  "subscriptionReferenceCode": "52c732ba-b449-460b-b553-ab21f9074300"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755679946462,
  "conversationId": "04c6063d-eb03-4817-ba87-33b81e392ecf",
  "token": "83832cc6-89b6-4a83-ac9f-dd996a52b2cb",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"83832cc6-89b6-4a83-ac9f-dd996a52b2cb\",price:1.00,...}};</script>",
  "tokenExpireTime": 1800
}

Sample Codes

PHP

Java

.NET

Node.js

Postman

Merchants can send the locale and conversationId parameters in all requests, but this is not mandatory. The locale parameter determines the language of the response. If specified as “EN”, error messages will be received in English. Conversation id is a value that software developers can use to match requests and responses. If this parameter is sent, the same value will be received in the response.

With this request, a checkout form is created and when the customer makes the payment, token information is sent to the specified callBackUrl address. In this case, the card has been updated successfully.