GitHubFeedback Form

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.

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
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
post
/v2/subscription/checkoutform/initialize

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
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
post
/v2/subscription/initialize

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
get
/v2/subscription/checkoutform/{token}

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
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
post
/v2/subscription/initialize/with-customer

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
subscriptionReferenceCodestringOptional

Reference code of the subscription that was started as pending.

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

Successful response

application/json
post
/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate

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
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
post
/v2/subscription/operation/retry

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
subscriptionReferenceCodestringOptional

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

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

Successful response

application/json
post
/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel

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
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
post
/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade

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

Successful response

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
get
/v2/subscription/subscriptions

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
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
post
/v2/subscription/card-update/checkoutform/initialize

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.

PreviousPayment PlanNextSubscriber Transactions

Last updated