Initialize Subscription

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

statusstring · enumOptional

Operation result.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755596201712

conversationIdstringOptional

Echoes the value you sent in the request.

Example: 123456789

tokenstringOptional

Token of the checkout form.

Example: a9f91f36-2110-4c55-848e-bdd2c7016171

checkoutFormContentstringOptional

HTML content of the checkout form.

tokenExpireTimeintegerOptional

Token validity time in seconds.

Example: 1800

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

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

statusstring · enumOptionalPossible values:

localestring · enumOptionalPossible values:

systemTimeintegerOptional

Current unix timestamp at the response time.

Example: 1755600509451

conversationIdstringOptional

Echoes the value you sent in the request.

Example: 123456789

tokenstringOptional

Token of the checkout form.

Example: 8e86b16e-9c0f-450d-a09d-0fd8a27e5197

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

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

statusstring · enumOptional

Indicates the request result; success if the operation succeeded.

Possible values:

systemTimeintegerOptional

Current unix timestamp at the response time.

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

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

statusstring · enumOptional

Operation result.

Possible values:

systemTimeintegerOptional

Operation time (epoch ms).

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