Cadence
API Reference

SDK Types

Shared TypeScript type definitions for API responses.

SDK Types

Shared TypeScript type definitions for working with the API responses.

SDK Types

cURL

# cURL doesn't use type definitions, but here's the expected JSON structure:

# ============================================
# Plan Types
# ============================================

# Plan object structure:
# {
#   "id": "string",
#   "segnoId": "string",
#   "referenceCode": "string",
#   "lookup_key": "string | null",
#   "name": "string",
#   "price": "string",
#   "currencyCode": "TRY" | "USD" | "EUR",
#   "paymentInterval": "DAILY" | "WEEKLY" | "MONTHLY" | "YEARLY",
#   "paymentIntervalCount": number,
#   "trialPeriodDays": number,
#   "unit": "string | null",
#   "productReference": "string | null",
#   "planType": "PHYSICAL" | "DIGITAL",
#   "shippingPrice": "string | null",
#   "gracePeriodDays": "number | null"
# }

# ============================================
# Checkout Types
# ============================================

# POST /checkout/initialize request:
# {
#   "pricingPlanReferenceCode": "string" (or "segno-plan-id", one required),
#   "segno-plan-id": "string" (or pricingPlanReferenceCode, one required),
#   "callbackUrl": "string" (required),
#   "name": "string" (required),
#   "surname": "string" (required),
#   "email": "string" (required),
#   "gsmNumber": "string" (required),
#   "identityNumber": "string" (required),
#   "subscriptionInitialStatus": "ACTIVE" | "PENDING" (optional),
#   "billingAddress": { ... } (optional),
#   "shippingAddress": { ... } (optional)
# }

# Checkout callback URL query parameters:
# Success: ?status=success&subscriptionReference=...&customerReference=...&planReference=...&segnoSubscriptionId=...&segnoCustomerId=...
# Error: ?status=error&errorCode=...&errorMessage=...

# ============================================
# Subscriber Types
# ============================================

# GET /subscribers query params:
#   ?iyzico-subscriber-code=... OR ?segno-id=...

# GET /subscribers response:
# {
#   "status": "success" | "failure",
#   "data": {
#     "id": "string",
#     "segnoId": "string",
#     "iyzicoReference": "string",
#     "customerReference": "string",
#     "planReference": "string",
#     "subscriptionStatus": "string",
#     "createdAt": "string",
#     "customer": { "id", "name", "surname", "email", "gsmNumber" } | null,
#     "latestInvoice": {
#       "id": "string",
#       "segnoId": "string",
#       "invoiceNumber": "string",
#       "status": "string",
#       "amount": "string",
#       "currency": "string",
#       "date": "string",
#       "pdfUrl": "string | null"
#     } | null
#   }
# }
#
# GET /subscribers/invoices query params:
#   ?subscriber-id=... OR ?segno-id=...
#   &limit=10
#   &starting_after=<invoice_uuid> (optional)
#   &ending_before=<invoice_uuid> (optional)
#
# GET /subscribers/invoices response:
# {
#   "status": "success",
#   "object": "list",
#   "url": "/subscribers/invoices",
#   "has_more": boolean,
#   "limit": number,
#   "subscriber": { "id", "segnoId", "subscriberId" },
#   "data": [
#     {
#       "id": "string",
#       "segnoId": "string",
#       "invoiceNumber": "string",
#       "status": "string",
#       "amount": "string",
#       "currency": "string",
#       "date": "string",
#       "pdfUrl": "string | null",
#       "signedPdf": {
#         "provider": "parasut",
#         "eArchiveId": "string",
#         "url": "string",
#         "expiresAt": "string | null",
#         "signedAt": "string"
#       } | null,
#       "pdfStatus": "ready" | "processing" | "unavailable" | "error",
#       "pdfMessage": "string | null"
#     }
#   ]
# }

# PUT /subscribers request (upgrade plan):
# Option 1: iyzico codes (syncs with iyzico)
# {
#   "iyzico-subscriber-reference-code": "string",
#   "iyzico-plan-reference-code": "string",
#   "resetRecurrenceCount": boolean (optional),
#   "useTrial": boolean (optional),
#   "upgradePeriod": "NOW" | "NEXT_PERIOD" (optional)
# }
# OR use segno IDs (database only):
# {
#   "segno-subscriber-id": "string",
#   "segno-plan-id": "string"
# }

# DELETE /subscribers request (cancel):
# {
#   "iyzico-subscriber-reference-code": "string" OR "segno-id": "string" (one required)
# }
# OR use segno ID (database only):
# {
#   "segno-id": "string"
# }
#
# POST /subscribers/undo-cancel request (undo cancel):
# {
#   "iyzico-subscriber-reference-code": "string" OR "segno-id": "string" (one required)
# }
# OR use segno ID (database only):
# {
#   "segno-id": "string"
# }

TypeScript

// ============================================
// Cadence API - TypeScript Types
// ============================================

// Address structure for billing/shipping
interface Address {
  contactName: string;
  country: string;
  city: string;
  address: string;
  zipCode?: string;
}

// ============================================
// Plans Types
// ============================================

// Plan object returned from /plans/list
interface Plan {
  id: string;
  segnoId: string;
  referenceCode: string;
  lookup_key: string | null;
  name: string;
  price: string;
  currencyCode: 'TRY' | 'USD' | 'EUR';
  paymentInterval: 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
  paymentIntervalCount: number;
  trialPeriodDays: number;
  unit: string | null;
  productReference: string | null;
  planType: 'PHYSICAL' | 'DIGITAL';
  shippingPrice: string | null;
  gracePeriodDays: number | null;
}

// Response from GET /plans/list
interface PlansListResponse {
  status: 'success';
  data: Plan[];
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

// ============================================
// Checkout Types
// ============================================

// Request body for POST /checkout/initialize
interface CheckoutInitializeRequest {
  pricingPlanReferenceCode?: string;
  'segno-plan-id'?: string;
  callbackUrl: string;
  name: string;
  surname: string;
  email: string;
  gsmNumber: string;
  identityNumber: string;
  subscriptionInitialStatus?: 'ACTIVE' | 'PENDING';
  billingAddress?: Address;
  shippingAddress?: Address;
}

// Response from POST /checkout/initialize
interface CheckoutInitializeResponse {
  status: 'success' | 'failure';
  checkoutFormContent?: string;
  token?: string;
  tokenExpireTime?: number;
  paymentPageUrl?: string;
  clientReferenceId?: string;
  segnoPlanId?: string | null;
  errorCode?: string;
  errorMessage?: string;
}

// Callback URL query parameters (redirect after checkout)
// Success: ?status=success&subscriptionReference=...&customerReference=...&planReference=...&segnoSubscriptionId=...&segnoCustomerId=...
// Error: ?status=error&errorCode=...&errorMessage=...
interface CheckoutCallbackSuccessParams {
  status: 'success';
  subscriptionReference: string;
  customerReference: string;
  planReference: string;
  segnoSubscriptionId: string;
  segnoCustomerId: string;
}

interface CheckoutCallbackErrorParams {
  status: 'error';
  errorCode: string;
  errorMessage: string;
}

type CheckoutCallbackParams = CheckoutCallbackSuccessParams | CheckoutCallbackErrorParams;

// ============================================
// Subscriber Types
// ============================================

// Customer info embedded in subscriber responses
interface CustomerInfo {
  id: string;
  name: string;
  surname: string;
  email: string;
  gsmNumber: string | null;
}

interface SubscriberLatestInvoice {
  id: string;
  segnoId: string;
  invoiceNumber: string;
  status: string;
  amount: string;
  currency: string;
  date: string;
  pdfUrl: string | null;
}

// Subscriber data returned from API
interface Subscriber {
  id: string;
  segnoId: string;
  iyzicoReference: string;
  customerReference: string;
  planReference: string;
  subscriptionStatus: string;
  createdAt: string;
  customer: CustomerInfo | null;
  latestInvoice: SubscriberLatestInvoice | null;
}

// Query params for GET /subscribers
interface GetSubscriberQuery {
  'iyzico-subscriber-code'?: string;  // Search by iyzico reference
  'segno-id'?: string;                // Search by internal ID
}

// Response from GET /subscribers
interface GetSubscriberResponse {
  status: 'success' | 'failure';
  data?: Subscriber;
  error?: string;
  message?: string;
}

// Query params for GET /subscribers/invoices
interface ListSubscriberInvoicesQuery {
  'subscriber-id'?: string;
  'segno-id'?: string;
  limit?: number;
  starting_after?: string; // invoice UUID cursor
  ending_before?: string; // invoice UUID cursor
}

interface SubscriberInvoiceListItem {
  id: string;
  segnoId: string;
  invoiceNumber: string;
  status: string;
  amount: string;
  currency: string;
  date: string;
  pdfUrl: string | null;
  signedPdf: {
    provider: 'parasut';
    eArchiveId: string;
    url: string;
    expiresAt: string | null;
    signedAt: string;
  } | null;
  pdfStatus: 'ready' | 'processing' | 'unavailable' | 'error';
  pdfMessage: string | null;
}

// Response from GET /subscribers/invoices
interface ListSubscriberInvoicesResponse {
  status: 'success';
  object: 'list';
  url: '/subscribers/invoices';
  has_more: boolean;
  limit: number;
  starting_after: string | null;
  ending_before: string | null;
  subscriber: {
    id: string;
    segnoId: string;
    subscriberId: string;
  };
  data: SubscriberInvoiceListItem[];
}

// Request body for PUT /subscribers (update/upgrade plan)
interface UpdateSubscriberRequest {
  // Option 1: Use iyzico codes (syncs with iyzico)
  'iyzico-subscriber-reference-code'?: string;
  'iyzico-plan-reference-code'?: string;
  // Option 2: Use segno IDs (database only, no iyzico sync)
  'segno-subscriber-id'?: string;
  'segno-plan-id'?: string;
  // Upgrade options (only for iyzico sync)
  resetRecurrenceCount?: boolean;
  useTrial?: boolean;
  upgradePeriod?: 'NOW' | 'NEXT_PERIOD';
}

// Response from PUT /subscribers
interface UpdateSubscriberResponse {
  status: 'success' | 'failure';
  message?: string;
  data?: {
    id: string;
    segnoId?: string;
    iyzicoReference: string;
    newPlanReference: string;
    newPlanSegnoId?: string;
    syncedWithIyzico: boolean;
    iyzicoResponse?: unknown;
  };
  error?: string;
}

// Request body for DELETE /subscribers (cancel subscription)
interface CancelSubscriberRequest {
  // Option 1: Use iyzico code (schedules cancellation at period end)
  'iyzico-subscriber-reference-code'?: string;
  // Option 2: Use segno ID (database only)
  'segno-id'?: string;
}

// Response from DELETE /subscribers
interface CancelSubscriberResponse {
  status: 'success' | 'failure';
  message?: string;
  data?: {
    id: string;
    segnoId?: string;
    iyzicoReference: string;
    status: 'ACTIVE';
    cancelAtPeriodEnd: boolean;
    cancelledAt: string;
    accessUntil: string | null;
    syncedWithIyzico: boolean;
  };
  error?: string;
}

// Request body for POST /subscribers/undo-cancel (undo cancellation)
interface UndoCancelSubscriberRequest {
  // Option 1: Use iyzico code (undo cancellation)
  'iyzico-subscriber-reference-code'?: string;
  // Option 2: Use segno ID (database only)
  'segno-id'?: string;
}

// Response from POST /subscribers/undo-cancel
interface UndoCancelSubscriberResponse {
  status: 'success' | 'failure';
  message?: string;
  data?: {
    id: string;
    segnoId?: string;
    iyzicoReference: string;
    status: 'ACTIVE';
    cancelAtPeriodEnd: boolean;
    cancelledAt: string | null;
    accessUntil: string | null;
    syncedWithIyzico: boolean;
  };
  error?: string;
}

Node.js

// ============================================
// Cadence API - Node.js Types (JSDoc)
// ============================================

/**
 * @typedef {Object} Address
 * @property {string} contactName
 * @property {string} country
 * @property {string} city
 * @property {string} address
 * @property {string} [zipCode]
 */

/**
 * @typedef {Object} Plan
 * @property {string} id
 * @property {string} segnoId
 * @property {string} referenceCode
 * @property {string|null} lookup_key
 * @property {string} name
 * @property {string} price
 * @property {'TRY'|'USD'|'EUR'} currencyCode
 * @property {'DAILY'|'WEEKLY'|'MONTHLY'|'YEARLY'} paymentInterval
 * @property {number} paymentIntervalCount
 * @property {number} trialPeriodDays
 * @property {string|null} unit
 * @property {string|null} productReference
 * @property {'PHYSICAL'|'DIGITAL'} planType
 * @property {string|null} shippingPrice
 * @property {number|null} gracePeriodDays
 */

/**
 * @typedef {Object} PlansListResponse
 * @property {Plan[]} data
 * @property {number} total
 * @property {number} page
 * @property {number} pageSize
 * @property {number} totalPages
 */

/**
 * @typedef {Object} CheckoutInitializeRequest
 * @property {string} [pricingPlanReferenceCode] - Or segno-plan-id (one required)
 * @property {string} [segno-plan-id] - Or pricingPlanReferenceCode (one required)
 * @property {string} callbackUrl
 * @property {string} name
 * @property {string} surname
 * @property {string} email
 * @property {string} gsmNumber
 * @property {string} identityNumber
 * @property {'ACTIVE'|'PENDING'} [subscriptionInitialStatus]
 * @property {Address} [billingAddress]
 * @property {Address} [shippingAddress]
 */

/**
 * @typedef {Object} CheckoutInitializeResponse
 * @property {'success'|'failure'} status
 * @property {string} [checkoutFormContent]
 * @property {string} [token]
 * @property {number} [tokenExpireTime]
 * @property {string} [clientReferenceId]
 * @property {string} [errorCode]
 * @property {string} [errorMessage]
 */

// Checkout Callback Types

/**
 * Callback URL query params on success:
 * ?status=success&subscriptionReference=...&customerReference=...&planReference=...&segnoSubscriptionId=...&segnoCustomerId=...
 * @typedef {Object} CheckoutCallbackSuccessParams
 * @property {'success'} status
 * @property {string} subscriptionReference
 * @property {string} customerReference
 * @property {string} planReference
 * @property {string} segnoSubscriptionId
 * @property {string} segnoCustomerId
 */

/**
 * Callback URL query params on error:
 * ?status=error&errorCode=...&errorMessage=...
 * @typedef {Object} CheckoutCallbackErrorParams
 * @property {'error'} status
 * @property {string} errorCode
 * @property {string} errorMessage
 */

// Subscriber Types

/**
 * @typedef {Object} CustomerInfo
 * @property {string} id
 * @property {string} name
 * @property {string} surname
 * @property {string} email
 * @property {string|null} gsmNumber
 */

/**
 * @typedef {Object} Subscriber
 * @property {string} id
 * @property {string} segnoId
 * @property {string} iyzicoReference
 * @property {string} customerReference
 * @property {string} planReference
 * @property {string} subscriptionStatus
 * @property {string} createdAt
 * @property {CustomerInfo|null} customer
 */

/**
 * @typedef {Object} GetSubscriberResponse
 * @property {'success'|'failure'} status
 * @property {Subscriber} [data]
 * @property {string} [error]
 * @property {string} [message]
 */

/**
 * @typedef {Object} UpdateSubscriberRequest
 * @property {string} [iyzico-subscriber-reference-code]
 * @property {string} [iyzico-plan-reference-code]
 * @property {string} [segno-subscriber-id]
 * @property {string} [segno-plan-id]
 * @property {boolean} [resetRecurrenceCount]
 * @property {boolean} [useTrial]
 * @property {'NOW'|'NEXT_PERIOD'} [upgradePeriod]
 */

/**
 * @typedef {Object} CancelSubscriberRequest
 * @property {string} [iyzico-subscriber-reference-code]
 * @property {string} [segno-id]
 */

/**
 * @typedef {Object} UndoCancelSubscriberRequest
 * @property {string} [iyzico-subscriber-reference-code]
 * @property {string} [segno-id]
 */

PHP

<?php
// ============================================
// Cadence API - PHP Types
// ============================================

class Address {
    public string $contactName;
    public string $country;
    public string $city;
    public string $address;
    public ?string $zipCode = null;
}

class Plan {
    public string $id;
    public string $segnoId;
    public string $referenceCode;
    public ?string $lookup_key;
    public string $name;
    public string $price;
    public string $currencyCode; // 'TRY' | 'USD' | 'EUR'
    public string $paymentInterval; // 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY'
    public int $paymentIntervalCount;
    public int $trialPeriodDays;
    public ?string $unit;
    public ?string $productReference;
    public string $planType; // 'PHYSICAL' | 'DIGITAL'
    public ?string $shippingPrice;
    public ?int $gracePeriodDays;
}

class PlansListResponse {
    /** @var Plan[] */
    public array $data;
    public int $total;
    public int $page;
    public int $pageSize;
    public int $totalPages;
}

class CheckoutInitializeRequest {
    public ?string $pricingPlanReferenceCode = null; // Or segno-plan-id (one required)
    public ?string $segnoPlanId = null; // JSON: "segno-plan-id"
    public string $callbackUrl;
    public string $name;
    public string $surname;
    public string $email;
    public string $gsmNumber;
    public string $identityNumber;
    public ?string $subscriptionInitialStatus = null; // 'ACTIVE' | 'PENDING'
    public ?Address $billingAddress = null;
    public ?Address $shippingAddress = null;
}

class CheckoutInitializeResponse {
    public string $status; // 'success' | 'failure'
    public ?string $checkoutFormContent = null;
    public ?string $token = null;
    public ?int $tokenExpireTime = null;
    public ?string $paymentPageUrl = null;
    public ?string $clientReferenceId = null;
    public ?string $segnoPlanId = null;
    public ?string $errorCode = null;
    public ?string $errorMessage = null;
}

// Checkout Callback params
class CheckoutCallbackSuccessParams {
    public string $status = 'success';
    public string $subscriptionReference;
    public string $customerReference;
    public string $planReference;
    public string $segnoSubscriptionId;
    public string $segnoCustomerId;
}

class CheckoutCallbackErrorParams {
    public string $status = 'error';
    public string $errorCode;
    public string $errorMessage;
}

// Subscriber Types
class CustomerInfo {
    public string $id;
    public string $name;
    public string $surname;
    public string $email;
    public ?string $gsmNumber = null;
}

class Subscriber {
    public string $id;
    public string $segnoId;
    public string $iyzicoReference;
    public string $customerReference;
    public string $planReference;
    public string $subscriptionStatus;
    public string $createdAt;
    public ?CustomerInfo $customer = null;
}

class GetSubscriberResponse {
    public string $status; // 'success' | 'failure'
    public ?Subscriber $data = null;
    public ?string $error = null;
    public ?string $message = null;
}

class UpdateSubscriberRequest {
    public ?string $iyzicoSubscriberReferenceCode = null;
    public ?string $iyzicoPlanReferenceCode = null;
    public ?string $segnoSubscriberId = null;
    public ?string $segnoPlanId = null;
    public ?bool $resetRecurrenceCount = null;
    public ?bool $useTrial = null;
    public ?string $upgradePeriod = null; // 'NOW' | 'NEXT_PERIOD'
}

class CancelSubscriberRequest {
    public ?string $iyzicoSubscriberReferenceCode = null;
    public ?string $segnoId = null;
}

class UndoCancelSubscriberRequest {
    public ?string $iyzicoSubscriberReferenceCode = null;
    public ?string $segnoId = null;
}

Go

package cadence

// ============================================
// Cadence API - Go Types
// ============================================

type Address struct {
    ContactName string  `json:"contactName"`
    Country     string  `json:"country"`
    City        string  `json:"city"`
    Address     string  `json:"address"`
    ZipCode     *string `json:"zipCode,omitempty"`
}

type Plan struct {
    ID                   string  `json:"id"`
    SegnoID              string  `json:"segnoId"`
    ReferenceCode        string  `json:"referenceCode"`
    LookupKey            *string `json:"lookup_key"`
    Name                 string  `json:"name"`
    Price                string  `json:"price"`
    CurrencyCode         string  `json:"currencyCode"`         // "TRY" | "USD" | "EUR"
    PaymentInterval      string  `json:"paymentInterval"`      // "DAILY" | "WEEKLY" | "MONTHLY" | "YEARLY"
    PaymentIntervalCount int     `json:"paymentIntervalCount"`
    TrialPeriodDays      int     `json:"trialPeriodDays"`
    Unit                 *string `json:"unit"`
    ProductReference     *string `json:"productReference"`
    PlanType             string  `json:"planType"`   // "PHYSICAL" | "DIGITAL"
    ShippingPrice        *string `json:"shippingPrice"`
    GracePeriodDays      *int    `json:"gracePeriodDays"`
}

type PlansListResponse struct {
    Status     string  `json:"status"`
    Data       []Plan  `json:"data"`
    Total      int    `json:"total"`
    Page       int    `json:"page"`
    PageSize   int    `json:"pageSize"`
    TotalPages int    `json:"totalPages"`
}

type CheckoutInitializeRequest struct {
    PricingPlanReferenceCode    *string  `json:"pricingPlanReferenceCode,omitempty"`
    SegnoPlanID                 *string  `json:"segno-plan-id,omitempty"`
    CallbackUrl                 string   `json:"callbackUrl"`
    Name                        string   `json:"name"`
    Surname                     string   `json:"surname"`
    Email                       string   `json:"email"`
    GsmNumber                   string   `json:"gsmNumber"`
    IdentityNumber              string   `json:"identityNumber"`
    SubscriptionInitialStatus   *string  `json:"subscriptionInitialStatus,omitempty"`
    BillingAddress              *Address `json:"billingAddress,omitempty"`
    ShippingAddress             *Address `json:"shippingAddress,omitempty"`
}

type CheckoutInitializeResponse struct {
    Status              string  `json:"status"`
    CheckoutFormContent *string `json:"checkoutFormContent,omitempty"`
    Token               *string `json:"token,omitempty"`
    TokenExpireTime     *int    `json:"tokenExpireTime,omitempty"`
    PaymentPageUrl      *string `json:"paymentPageUrl,omitempty"`
    ClientReferenceId   *string `json:"clientReferenceId,omitempty"`
    SegnoPlanId         *string `json:"segnoPlanId,omitempty"`
    ErrorCode           *string `json:"errorCode,omitempty"`
    ErrorMessage        *string `json:"errorMessage,omitempty"`
}

// Checkout Callback Types
type CheckoutCallbackSuccessParams struct {
    Status                string `json:"status"`
    SubscriptionReference string `json:"subscriptionReference"`
    CustomerReference     string `json:"customerReference"`
    PlanReference         string `json:"planReference"`
    SegnoSubscriptionId   string `json:"segnoSubscriptionId"`
    SegnoCustomerId       string `json:"segnoCustomerId"`
}

type CheckoutCallbackErrorParams struct {
    Status       string `json:"status"`
    ErrorCode    string `json:"errorCode"`
    ErrorMessage string `json:"errorMessage"`
}

// Subscriber Types
type CustomerInfo struct {
    ID        string  `json:"id"`
    Name      string  `json:"name"`
    Surname   string  `json:"surname"`
    Email     string  `json:"email"`
    GsmNumber *string `json:"gsmNumber"`
}

type Subscriber struct {
    ID                 string        `json:"id"`
    SegnoID            string        `json:"segnoId"`
    IyzicoReference    string        `json:"iyzicoReference"`
    CustomerReference  string        `json:"customerReference"`
    PlanReference      string        `json:"planReference"`
    SubscriptionStatus string        `json:"subscriptionStatus"`
    CreatedAt          string        `json:"createdAt"`
    Customer           *CustomerInfo `json:"customer"`
}

type GetSubscriberResponse struct {
    Status  string      `json:"status"`
    Data    *Subscriber `json:"data,omitempty"`
    Error   *string     `json:"error,omitempty"`
    Message *string     `json:"message,omitempty"`
}

type UpdateSubscriberRequest struct {
    IyzicoSubscriberReferenceCode *string `json:"iyzico-subscriber-reference-code,omitempty"`
    IyzicoPlanReferenceCode       *string `json:"iyzico-plan-reference-code,omitempty"`
    SegnoSubscriberId             *string `json:"segno-subscriber-id,omitempty"`
    SegnoPlanId                   *string `json:"segno-plan-id,omitempty"`
    ResetRecurrenceCount          *bool   `json:"resetRecurrenceCount,omitempty"`
    UseTrial                      *bool   `json:"useTrial,omitempty"`
    UpgradePeriod                 *string `json:"upgradePeriod,omitempty"`
}

type CancelSubscriberRequest struct {
    IyzicoSubscriberReferenceCode *string `json:"iyzico-subscriber-reference-code,omitempty"`
    SegnoId                       *string `json:"segno-id,omitempty"`
}

type UndoCancelSubscriberRequest struct {
    IyzicoSubscriberReferenceCode *string `json:"iyzico-subscriber-reference-code,omitempty"`
    SegnoId                       *string `json:"segno-id,omitempty"`
}

Ruby

# ============================================
# Cadence API - Ruby Types (Sorbet)
# ============================================

# typed: strict
extend T::Sig

class Address < T::Struct
  const :contact_name, String
  const :country, String
  const :city, String
  const :address, String
  const :zip_code, T.nilable(String)
end

class Plan < T::Struct
  const :id, String
  const :segno_id, String
  const :reference_code, String
  const :lookup_key, T.nilable(String)
  const :name, String
  const :price, String
  const :currency_code, T.any(String) # 'TRY' | 'USD' | 'EUR'
  const :payment_interval, T.any(String) # 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY'
  const :payment_interval_count, Integer
  const :trial_period_days, Integer
  const :unit, T.nilable(String)
  const :product_reference, T.nilable(String)
  const :plan_type, String # 'PHYSICAL' | 'DIGITAL'
  const :shipping_price, T.nilable(String)
  const :grace_period_days, T.nilable(Integer)
end

class PlansListResponse < T::Struct
  const :status, String
  const :data, T::Array[Plan]
  const :total, Integer
  const :page, Integer
  const :page_size, Integer
  const :total_pages, Integer
end

class CheckoutInitializeRequest < T::Struct
  const :pricing_plan_reference_code, T.nilable(String) # Or segno_plan_id (one required)
  const :segno_plan_id, T.nilable(String) # JSON: "segno-plan-id"
  const :callback_url, String
  const :name, String
  const :surname, String
  const :email, String
  const :gsm_number, String
  const :identity_number, String
  const :subscription_initial_status, T.nilable(String)
  const :billing_address, T.nilable(Address)
  const :shipping_address, T.nilable(Address)
end

class CheckoutInitializeResponse < T::Struct
  const :status, String # 'success' | 'failure'
  const :checkout_form_content, T.nilable(String)
  const :token, T.nilable(String)
  const :token_expire_time, T.nilable(Integer)
  const :payment_page_url, T.nilable(String)
  const :client_reference_id, T.nilable(String)
  const :segno_plan_id, T.nilable(String)
  const :error_code, T.nilable(String)
  const :error_message, T.nilable(String)
end

# Checkout Callback Types
class CheckoutCallbackSuccessParams < T::Struct
  const :status, String # 'success'
  const :subscription_reference, String
  const :customer_reference, String
  const :plan_reference, String
  const :segno_subscription_id, String
  const :segno_customer_id, String
end

class CheckoutCallbackErrorParams < T::Struct
  const :status, String # 'error'
  const :error_code, String
  const :error_message, String
end

# Subscriber Types
class CustomerInfo < T::Struct
  const :id, String
  const :name, String
  const :surname, String
  const :email, String
  const :gsm_number, T.nilable(String)
end

class Subscriber < T::Struct
  const :id, String
  const :segno_id, String
  const :iyzico_reference, String
  const :customer_reference, String
  const :plan_reference, String
  const :subscription_status, String
  const :created_at, String
  const :customer, T.nilable(CustomerInfo)
end

class GetSubscriberResponse < T::Struct
  const :status, String
  const :data, T.nilable(Subscriber)
  const :error, T.nilable(String)
  const :message, T.nilable(String)
end

class UpdateSubscriberRequest < T::Struct
  const :iyzico_subscriber_reference_code, T.nilable(String)
  const :iyzico_plan_reference_code, T.nilable(String)
  const :segno_subscriber_id, T.nilable(String)
  const :segno_plan_id, T.nilable(String)
  const :reset_recurrence_count, T.nilable(T::Boolean)
  const :use_trial, T.nilable(T::Boolean)
  const :upgrade_period, T.nilable(String)
end

class CancelSubscriberRequest < T::Struct
  const :iyzico_subscriber_reference_code, T.nilable(String)
  const :segno_id, T.nilable(String)
end

class UndoCancelSubscriberRequest < T::Struct
  const :iyzico_subscriber_reference_code, T.nilable(String)
  const :segno_id, T.nilable(String)
end

Python

# ============================================
# Cadence API - Python Types
# ============================================

from dataclasses import dataclass
from typing import List, Optional, Literal
from enum import Enum

class CurrencyCode(Enum):
    TRY = "TRY"
    USD = "USD"
    EUR = "EUR"

class PaymentInterval(Enum):
    DAILY = "DAILY"
    WEEKLY = "WEEKLY"
    MONTHLY = "MONTHLY"
    YEARLY = "YEARLY"

@dataclass
class Address:
    contact_name: str
    country: str
    city: str
    address: str
    zip_code: Optional[str] = None

@dataclass
class Plan:
    id: str
    segno_id: str
    reference_code: str
    lookup_key: Optional[str]
    name: str
    price: str
    currency_code: CurrencyCode
    payment_interval: PaymentInterval
    payment_interval_count: int
    trial_period_days: int
    unit: Optional[str]
    product_reference: Optional[str]
    plan_type: Literal["PHYSICAL", "DIGITAL"]
    shipping_price: Optional[str]
    grace_period_days: Optional[int]

@dataclass
class PlansListResponse:
    status: Literal["success"]
    data: List[Plan]
    total: int
    page: int
    page_size: int
    total_pages: int

@dataclass
class CheckoutInitializeRequest:
    pricing_plan_reference_code: Optional[str] = None  # Or segno_plan_id (one required)
    segno_plan_id: Optional[str] = None  # JSON: "segno-plan-id"
    callback_url: str = ""
    name: str = ""
    surname: str = ""
    email: str = ""
    gsm_number: str = ""
    identity_number: str = ""
    subscription_initial_status: Optional[Literal["ACTIVE", "PENDING"]] = None
    billing_address: Optional[Address] = None
    shipping_address: Optional[Address] = None

@dataclass
class CheckoutInitializeResponse:
    status: Literal["success", "failure"]
    checkout_form_content: Optional[str] = None
    token: Optional[str] = None
    token_expire_time: Optional[int] = None
    payment_page_url: Optional[str] = None
    client_reference_id: Optional[str] = None
    segno_plan_id: Optional[str] = None
    error_code: Optional[str] = None
    error_message: Optional[str] = None

# Checkout Callback Types
@dataclass
class CheckoutCallbackSuccessParams:
    status: Literal["success"]
    subscription_reference: str
    customer_reference: str
    plan_reference: str
    segno_subscription_id: str
    segno_customer_id: str

@dataclass
class CheckoutCallbackErrorParams:
    status: Literal["error"]
    error_code: str
    error_message: str

# Subscriber Types
@dataclass
class CustomerInfo:
    id: str
    name: str
    surname: str
    email: str
    gsm_number: Optional[str] = None

@dataclass
class Subscriber:
    id: str
    segno_id: str
    iyzico_reference: str
    customer_reference: str
    plan_reference: str
    subscription_status: str
    created_at: str
    customer: Optional[CustomerInfo] = None

@dataclass
class GetSubscriberResponse:
    status: Literal["success", "failure"]
    data: Optional[Subscriber] = None
    error: Optional[str] = None
    message: Optional[str] = None

@dataclass
class UpdateSubscriberRequest:
    iyzico_subscriber_reference_code: Optional[str] = None
    iyzico_plan_reference_code: Optional[str] = None
    segno_subscriber_id: Optional[str] = None
    segno_plan_id: Optional[str] = None
    reset_recurrence_count: Optional[bool] = None
    use_trial: Optional[bool] = None
    upgrade_period: Optional[Literal["NOW", "NEXT_PERIOD"]] = None

@dataclass
class CancelSubscriberRequest:
    iyzico_subscriber_reference_code: Optional[str] = None
    segno_id: Optional[str] = None

@dataclass
class UndoCancelSubscriberRequest:
    iyzico_subscriber_reference_code: Optional[str] = None
    segno_id: Optional[str] = None

Webhooks

Receive real-time subscription lifecycle events and verify their signatures.

Integration Example

End-to-end integration walkthrough.

On this page

SDK TypesSDK TypescURLTypeScriptNode.jsPHPGoRubyPython