Payment Plan
The subscription system operates by default according to the specified plan. The payment plan is the step where all the necessary features for recurring payments are specified.
Plans have unique names, and one plan can only be associated with one product. If a plan is actively linked to a subscription, it cannot be deleted.
There are five different methods that can be used on plans.
Create Payment Plan
To create a plan, the following details must be provided: product reference number, name, price, currency, payment interval, and other parameters as detailed below.
If a trial period is desired for a subscription, the trialPeriodDays parameter can be used. If this parameter is sent, no subscription will be initiated and no payment will be collected from the card during the specified period.
The Payment Interval parameter specified in the request indicates the payment period. When sending the "WEEKLY" parameter when creating a plan, iyzico will deduct the specified amount from the card every week. Customizing this period is also possible. For example, if you want payments to be collected every 2 weeks, you should send the PaymentInterval value as "WEEKLY" and the paymentIntervalCount value as 2.
The planPaymentType parameter is mandatory and can currently only take the value RECURRING.
Create Payment Plan
POST
https://api.iyzipay.com/v2/subscription/products/{product_reference}/pricing-plans
Request Body
Name | Type | Description |
---|---|---|
conversationId | String | A value that can be sent during the request and received in the response, used to match the request and response. The most common usage is the plan number of the merchant. |
locale | String | It is used to set the language of the text returned as a result of the iyzico request. The default value is TR (Turkish). |
name* | String | Plan name. A value should be entered that provides a brief description related to the payment plan. |
productReferenceCode* | String | The reference code of the product to which the plan will be associated. |
recurrenceCount | Integer | Determines how many times the payment period will be repeated. For example, if you set this value to 12 for a plan that receives monthly payments, payments will be collected for 12 months. |
planPaymentType* | String | Specifies the subscription type. The value entered should be RECURRING. |
trialPeriodDays | Integer | Used as a trial period or free usage period. If this value is entered, the first payment is collected after the specified number of days from the day of entry. |
paymentIntervalCount* | Integer | Determines the frequency of the payment period. For example, if the paymentInterval value is WEEKLY and the paymentIntervalCount value is 2, payments are collected every 2 weeks. |
paymentInterval* | String | Determines the period for collecting recurring payments. It can take values of DAILY, WEEKLY, MONTHLY, YEARLY. |
currencyCode* | String | The currency in which the payment will be collected. It can be TL (Turkish Lira), USD (US Dollar), EUR (Euro), etc. Ensure that currencies other than TL are defined in your account. |
price* | Decimal | The amount to be charged from the card during payment intervals. The current subscription price for the plan. |
Create Payment Plan Response
Parameter Name | Type | Description |
---|---|---|
status | String | It indicates the result of the request. If the transaction is successful, it returns a 'success' value. |
systemTime | Long | The returned result is the current Unix timestamp value at that moment. |
referenceCode | String | The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription. |
createdDate | Long | The date of plan creation |
name | String | The name of the plan. |
productReferenceCode | String | The reference code of the product associated with the plan. The product information sent in the request is returned. |
price | Decimal | The value sent in the request is returned. It is the amount to be collected from the card during payment intervals. |
currencyCode | String | The value sent in the request is returned. It is the currency in which the payment will be collected. |
paymentInterval | String | The value sent in the request is returned. It determines the period for collecting recurring payments. |
paymentIntervalCount | Integer | The value sent in the request is returned. It determines the frequency of the payment period |
trialPeriodDays | Integer | The value sent in the request is returned. If this value was not sent, it returns as 0. |
planPaymentType | String | It returns the value RECURRING, indicating that the payment is recurring. |
recurrenceCount | Integer | The value sent in the request is returned. It determines how many times the payment period will be repeated (optional). |
status | String | It indicates the status of the plan. It takes the value ACTIVE. |
Update Payment Plan
This method allows only the updating of the name and trialPeriodDays parameters. To update a plan, the unique reference code associated with that plan must be used. Updating can be done both through the API and the iyzico merchant panel.
Update Payment Plan
POST
https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}
Request Body
Name | Type | Description |
---|---|---|
conversationId | String | A value that can be sent during the request and received in the response, used to match the request and response. The most common usage is the plan number of the merchant. |
locale | String | It is used to set the language of the text returned as a result of the iyzico request. The default value is TR (Turkish). |
name* | String | Plan name. A value should be entered that provides a brief description related to the payment plan. |
pricingPlanReferenceCode* | String | The reference code of the product to which the plan will be associated. |
trialPeriodDays | Integer | Used as a trial period or free usage period. If this value is entered, the first payment is collected after the specified number of days from the day of entry. |
Update Payment Plan Response
Parameter Name | Type | Description |
---|---|---|
status | String | It indicates the result of the request. If the transaction is successful, it returns a 'success' value. |
systemTime | Long | The returned result is the current Unix timestamp value at that moment. |
referenceCode | String | The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription. |
createdDate | Long | The date of plan creation. |
name | String | The name of the plan. |
productReferenceCode | String | The reference code of the product associated with the plan. The product information sent in the request is returned. |
price | Decimal | The value sent in the request is returned. It is the amount to be collected from the card during payment intervals. |
currencyCode | String | The value sent in the request is returned. It is the currency in which the payment will be collected. |
paymentInterval | String | The value sent in the request is returned. It determines the period for collecting recurring payments. |
paymentIntervalCount | Integer | The value sent in the request is returned. It determines the frequency of the payment period |
trialPeriodDays | Integer | The value sent in the request is returned. If this value was not sent, it returns as 0. |
planPaymentType | String | It returns the value RECURRING, indicating that the payment is recurring. |
recurrenceCount | Integer | The value sent in the request is returned. It determines how many times the payment period will be repeated (optional). |
status | String | It indicates the status of the plan. It takes the value ACTIVE. |
Delete Payment Plan
A plan can only be deleted if it has no associated subscriptions. To delete a plan, the merchant must use the plan reference code. The request is responded to as either success or failure. Success means the plan has been successfully deleted.
Delete Payment Plan
DELETE
https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}
Request Body
Name | Type | Description |
---|---|---|
pricingPlanReferenceCodee* | String | The reference code of the product to which the plan will be associated. |
Delete Payment Plan Response
Parametre ismi | Tip | Açıklama |
---|---|---|
status | String | Yapılan isteğin sonucunu belirtir. İşlem başarılı ise success değeri döner. |
systemTime | Long | Dönen sonucun o anki unix timestamp değeridir. |
Get Payment Plan
Merchant businesses can view all the details of a plan both through the merchant panel and via API requests.
Get Payment Plan
GET
https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}
Request Body
Name | Type | Description |
---|---|---|
pricingPlanReferenceCode* | String | The reference code of the product to which the plan will be associated. |
Get Payment Plan Response
Parameter Name | Type | Description |
---|---|---|
status | String | It indicates the result of the request. If the transaction is successful, it returns a 'success' value. |
systemTime | Long | The returned result is the current Unix timestamp value at that moment. |
referenceCode | String | The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription. |
createdDate | Long | The date of plan creation. |
name | String | The name of the plan. |
productReferenceCode | String | The reference code of the product associated with the plan. The product information sent in the request is returned. |
price | Decimal | The value sent in the request is returned. It is the amount to be collected from the card during payment intervals. |
currencyCode | String | The value sent in the request is returned. It is the currency in which the payment will be collected. |
paymentInterval | String | The value sent in the request is returned. It determines the period for collecting recurring payments. |
paymentIntervalCount | Integer | The value sent in the request is returned. It determines the frequency of the payment period |
trialPeriodDays | Integer | The value sent in the request is returned. If this value was not sent, it returns as 0. |
planPaymentType | String | It returns the value RECURRING, indicating that the payment is recurring. |
recurrenceCount | Integer | The value sent in the request is returned. It determines how many times the payment period will be repeated (optional). |
status | String | It indicates the status of the plan. It takes the value ACTIVE. |
List of Payment Plans
All plans and the products they are associated with can be viewed in the response to this request. The response is sent in pages.
List of Payment Plans
GET
https://api.iyzipay.com/v2/subscription/products/{product_reference}/pricing-plans
Request Body
Name | Type | Description |
---|---|---|
page* | Integer | It retrieves all the plans for the specified page. |
count* | Integer | It specifies how many plans will be listed per page. |
List of Payment Plan Response
Parametre ismi | Tip | Açıklama |
---|---|---|
status | String | It indicates the result of the request. If the transaction is successful, it returns a 'success' value. |
systemTime | Long | The returned result is the current Unix timestamp value at that moment. |
totalCount | String | It indicates the total number of results. |
currentPage | Integer | It specifies which page the listing is for. |
pageCount | Integer | It indicates the total number of pages of results. |
items | Array Object | It is an array containing plan details. |
Last updated