🔄 Recurring Payment Operations

📝 Create Recurring Payment

Endpoint

POST /recurring

Description

Creates a recurring payment (subscription) that will be automatically executed at regular intervals. Payments can be scheduled on daily, monthly, or yearly periods.

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request: RecurringPaymentRequest

{
  "reference": "SUB-2026-001",
  "amount": 99.90,
  "currencyCode": "TRY",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "explanation": "Premium subscription - monthly",
  "ownerDescription": {
    "fullName": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "+905559876543",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "paymentChannel": "mobile",
  "firstPaymentTime": "2026-03-01T00:00:00Z",
  "lastPaymentTime": "2027-03-01T00:00:00Z",
  "frequency": "monthly",
  "interval": 1,
  "dayOfMonth": 1
}

Parameters

Parameter	Type	Required	Description
reference	string	✅	Subscription reference code (max 150 characters)
amount	number	✅	Amount for each payment
currencyCode	string	✅	Currency code (e.g., TRY, USD, EUR)
paymentSystemId	uuid	❌	Payment system ID to use
explanation	string	❌	Payment description (max 400 characters)
ownerDescription	object	✅	Card owner information
paymentChannel	string	❌	Payment channel (max 50 characters)
firstPaymentTime	datetime	✅	First payment date (ISO 8601)
lastPaymentTime	datetime	❌	Last payment date (ISO 8601)
frequency	string	✅	Payment frequency: daily, monthly, yearly
interval	integer	✅	Period interval (between 1-30)
monthOfYear	integer	⚠️	Month of year (1-12) - required for yearly
dayOfMonth	integer	⚠️	Day of month (1-30) - required for monthly/yearly

Frequency Values

Value	Description	Example
daily	Daily	Every 1 day, every 5 days, etc.
monthly	Monthly	1st of every month, 15th of every month, etc.
yearly	Yearly	January 1st every year, etc.

Response

Successful Request (200 OK)

{
  "success": true,
  "error": null,
  "shouldBeOwnerConfirmation": false,
  "ownerId": "OWN-123456",
  "orderStatus": "active"
}

Error (403 Forbidden)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "instance": "/recurring"
}

---

📋 List Recurring Payments

Endpoint

GET /recurring

Description

Lists existing recurring payments. Supports filtering, pagination, and sorting.

Query Parameters

Parameter	Type	Required	Description
Subscription	string	❌	Filter by subscription ID
Page	integer	❌	Page number (default: 1)
PageSize	integer	❌	Records per page
OrderBy	string	❌	Sort field
Dir	string	❌	Sort direction: asc or desc

Example Request

GET /recurring?Page=1&PageSize=10&OrderBy=createdAtUtc&Dir=desc

Response: RecurringPaymentModelPagedList

{
  "currentPage": 1,
  "pageCount": 5,
  "totalCount": 47,
  "hasNext": true,
  "hasPrevious": false,
  "stateKey": "abc123",
  "pages": [1, 2, 3, 4, 5],
  "list": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 99.90,
      "currencyCode": "TRY",
      "status": "active",
      "createdAtUtc": "2026-02-16T10:00:00Z",
      "reference": "SUB-2026-001",
      "explanation": "Premium subscription - monthly",
      "interval": 1,
      "dayOfMonth": 1,
      "monthOfYear": null,
      "nextPaymentAtUtc": "2026-03-01T00:00:00Z",
      "lastPaymentAtUtc": "2026-02-01T00:00:00Z",
      "phone": "+905559876543",
      "email": "jane.smith@example.com"
    }
  ]
}

---

✏️ Update Recurring Payment

Endpoint 1: Update by Subscription ID

PUT /recurring/subscription/{subscription}

Endpoint 2: Update by UUID

PUT /recurring/{id}

Description

Updates parameters of an existing recurring payment. Amount, currency, frequency, and other settings can be changed.

Path Parameters

Parameter	Type	Description
subscription	string	Subscription ID (string)
id	uuid	Recurring payment UUID

Request: UpdateRecurringPaymentRequest

{
  "amount": 119.90,
  "currencyCode": "TRY",
  "explanation": "Premium Plus subscription - monthly",
  "lastPaymentTime": "2028-03-01T00:00:00Z",
  "paymentSystemGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "paymentChannel": "mobile",
  "frequency": "monthly",
  "status": "active",
  "interval": 1,
  "dayOfMonth": 1
}

Parameters

Parameter	Type	Required	Description
amount	number	✅	Updated payment amount
currencyCode	string	✅	Currency code
explanation	string	❌	Description (max 400 characters)
lastPaymentTime	datetime	❌	Last payment date
paymentSystemGroupId	uuid	❌	Payment system group ID
paymentSystemId	uuid	❌	Payment system ID
paymentChannel	string	❌	Payment channel (max 50 characters)
frequency	string	❌	Payment frequency
status	string	❌	Status change
interval	integer	❌	Period interval (1-30)
monthOfYear	integer	⚠️	Month of year (1-12)
dayOfMonth	integer	⚠️	Day of month (1-30)

Response

Successful Request (200 OK)

{
  "success": true
}

---

Example Usage

cURL - Create

curl -X POST https://pgw.klogs.io/recurring \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SUB-2026-001",
    "amount": 99.90,
    "currencyCode": "TRY",
    "ownerDescription": {
      "fullName": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+905559876543",
      "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "firstPaymentTime": "2026-03-01T00:00:00Z",
    "frequency": "monthly",
    "interval": 1,
    "dayOfMonth": 1
  }'

JavaScript - List

const response = await fetch('https://pgw.klogs.io/recurring?Page=1&PageSize=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.list);

C# - Update

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var updateRequest = new {
    amount = 119.90,
    currencyCode = "TRY",
    status = "active"
};

var content = new StringContent(
    JsonSerializer.Serialize(updateRequest),
    Encoding.UTF8,
    "application/json"
);

var subscriptionId = "SUB-2026-001";
var response = await client.PutAsync(
    $"https://pgw.klogs.io/recurring/subscription/{subscriptionId}",
    content
);

Notes

• firstPaymentTime must be in the future when creating recurring payments
• interval value must be between 1-30
• dayOfMonth parameter is required for monthly payments
• dayOfMonth and monthOfYear parameters are required for yearly payments
• Payments are automatically processed when subscription status is active
• To stop a subscription, update the status to disabled
• There is an automatic retry mechanism for failed payments

Related Endpoints

• Card Owner Registration
• Create Payment Order
• Webhook Operations