Create a subscription

A subscription is created by sending SUBSCRIPTION in the paymentGroup field of the checkout initiation request. After the initial 3D Secure payment succeeds, subsequent charges are processed according to the plan.

HTTP method URL
POST /payment/v1/checkout-payments/init

Plan fields

Field Type Required Description
externalCustomerId string No Customer identifier in the merchant system. Maximum 255 characters.
planCode string No Plan code in the merchant system. Maximum 50 characters.
periodType integer Yes Billing period: 7 (week), 30 (month), or 365 (year).
price decimal Conditional Fixed amount per period. Must be positive.
nochargeDayCount integer Yes Number of free days before the first charge. Defaults to 0.
description string Yes Subscription description.
paymentCount integer No Total number of billing periods.
variablePayment boolean No Indicates whether the plan has variable amounts.
variablePaymentTriggerType string Conditional Variable plan trigger: SCHEDULED or EXTERNAL.
paymentSteps array No Period-based amount and payment-date steps.

Payment step fields

Field Type Required Description
startPeriod integer Yes First period of the step. Minimum 1.
periodPrice decimal Yes Amount for the period. Must be greater than 0.
paymentDate date Yes Charge date (YYYY-MM-DD).
skipPaymentPeriod boolean No Indicates that the period should be skipped without a charge.

Example request

{
  "price": 99.90,
  "paidPrice": 99.90,
  "currency": "TRY",
  "paymentGroup": "SUBSCRIPTION",
  "callbackUrl": "https://merchant.example.com/payment/callback",
  "conversationId": "order-2026-001",
  "items": [
    { "name": "Premium membership", "price": 99.90 }
  ],
  "plan": {
    "externalCustomerId": "customer-42",
    "planCode": "PREMIUM-MONTHLY",
    "periodType": 30,
    "price": 99.90,
    "nochargeDayCount": 0,
    "description": "Monthly premium membership",
    "paymentCount": 12,
    "variablePayment": false
  }
}

The successful response is documented under Checkout Page. The subscription identifier is created after the initial payment succeeds.

Subscription statuses

Value Numeric value Description
ACTIVE 0 The subscription is active.
PASSIVE 1 The subscription is paused.
PENDING 2 The initial or next operation is pending.
DELETED 3 The subscription is deleted.
PROCESSING 4 A charge is being processed.
ANOMALY 5 Payment and subscription state are inconsistent.
WAITING 6 The next charge attempt is pending.