💳 Registered Payment API

Overview

The Registered Payment API (Recurring and Payment Order API) provides a comprehensive solution for managing recurring payments (subscriptions) and future payment orders. With this API, you can securely store customer card information and create automatic payments.

Features

✅ Secure Card Storage - PCI-DSS compliant card information storage
✅ Recurring Payments - Daily, monthly, or yearly subscriptions
✅ Payment Orders - Future one-time payments
✅ Webhook Notifications - Real-time payment status updates
✅ Flexible Periods - Customizable payment frequencies
✅ Status Management - Activate/deactivate subscriptions

API Version

v0.50

Base URL

Test Environment

https://pgw.klogs.dev/

Production Environment

https://pgw.klogs.io/

Authentication

All API requests require Bearer token authentication.

http

Authorization: Bearer YOUR_API_KEY

⚠️ Security Warning: Never share your API key in public repositories.

Quick Start

1️⃣ Register Card Owner

First, register the card owner in the system:

bash

curl -X POST https://pgw.klogs.io/owner \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+905551234567"}'

2️⃣ Create Recurring Payment

Create a monthly subscription:

bash

curl -X POST https://pgw.klogs.io/recurring \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SUB-001",
    "amount": 99.90,
    "currencyCode": "TRY",
    "ownerDescription": {
      "fullName": "John Doe",
      "phone": "+905551234567",
      "email": "john@example.com",
      "cardId": "CARD_UUID"
    },
    "firstPaymentTime": "2026-03-01T00:00:00Z",
    "frequency": "monthly",
    "interval": 1,
    "dayOfMonth": 1
  }'

3️⃣ Configure Webhook

Configure your webhook endpoint to receive notifications when card storage is completed:

javascript

app.post('/webhooks/card-storage/:type/:id', (req, res) => {
  const { cardId, ownerId } = req.body;
  console.log(`Card ${cardId} saved for owner ${ownerId}`);
  res.json({ success: true });
});

API Endpoints

Card Owner Operations

Method	Endpoint	Description
POST	/owner	Creates a card owner record

Detailed Documentation →

Payment Order Operations

Method	Endpoint	Description
POST	/paymentOrder	Creates a future payment order

Detailed Documentation →

Recurring Payment Operations

Method	Endpoint	Description
POST	/recurring	Creates a new recurring payment
GET	/recurring	Lists recurring payments
PUT	/recurring/	Updates by UUID
PUT	/recurring/subscription/	Updates by subscription ID

Detailed Documentation →

Webhook Operations

Method	Endpoint	Description
POST	/api/return/webhook/complete-cardstorage/{type}/	Card storage completion webhook

Detailed Documentation →

Data Models

RegisteredPaymentStatus

Payment record statuses:

Status	Description
`active`	Active - payments will be processed
`disabled`	Disabled - no payments will be made
`complete`	Completed
`waitForOwnerConfirmation`	Waiting for card owner confirmation
`waitForCardSave`	Waiting for card save

RecurringPaymentFrequence

Payment frequency values:

Value	Description
`daily`	Daily payments
`monthly`	Monthly payments
`yearly`	Yearly payments

OrderDirection

Sort direction:

Value	Description
`asc`	Ascending order
`desc`	Descending order

Use Cases

Scenario 1: Monthly Subscription

Monthly subscription for a Netflix-like streaming service:

json

{
  "reference": "NETFLIX-USER-123",
  "amount": 99.99,
  "currencyCode": "TRY",
  "frequency": "monthly",
  "interval": 1,
  "dayOfMonth": 1,
  "explanation": "Premium subscription"
}

Scenario 2: Quarterly Payment

Payment every three months:

json

{
  "reference": "QUARTERLY-SUBSCRIPTION",
  "amount": 250.00,
  "currencyCode": "TRY",
  "frequency": "monthly",
  "interval": 3,
  "dayOfMonth": 15,
  "explanation": "3-month subscription"
}

Scenario 3: Annual Renewal

Payment on January 1st every year:

json

{
  "reference": "ANNUAL-LICENSE",
  "amount": 999.00,
  "currencyCode": "TRY",
  "frequency": "yearly",
  "interval": 1,
  "monthOfYear": 1,
  "dayOfMonth": 1,
  "explanation": "Annual license fee"
}

Scenario 4: One-Time Future Payment

One-time payment 3 months from now:

json

{
  "reference": "FUTURE-PAYMENT-001",
  "amount": 500.00,
  "currencyCode": "TRY",
  "paymentTime": "2026-05-16T10:00:00Z",
  "explanation": "Payment in 3 months"
}

Error Handling

The API uses standard HTTP status codes and RFC 7807 Problem Details format.

Example Error Response

json

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "detail": "The amount field is required.",
  "instance": "/recurring"
}

Common HTTP Codes

Code	Meaning	Description
200	OK	Operation successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Authentication failed
403	Forbidden	Unauthorized access
404	Not Found	Resource not found
500	Internal Server Error	Server error

Rate Limiting

API requests are subject to rate limiting:

Test Environment: 100 requests/minute
Production Environment: 1000 requests/minute

When the rate limit is exceeded, you'll receive a 429 Too Many Requests response.

Security

Best Practices

✅ Use HTTPS - Send all requests over HTTPS
✅ Token Security - Store API keys in environment variables
✅ Webhook Validation - Validate webhooks with hash verification
✅ IP Whitelisting - Apply IP restrictions when possible
✅ Logging - Log all operations

PCI-DSS Compliance

Klogs Payment Gateway is PCI-DSS Level 1 certified. Card information:

Encrypted with AES-256
Tokenized
Stored in secure vault
Never logged in plain text

Support and Contact

Technical Support

Email: info@klogs.com.tr
Web: https://klogs.com.tr/contact
Documentation: https://docs.klogs.com.tr

License

This API is licensed under KLOGS License.
Details: https://klogs.com.tr/license

Terms of Service

Service terms: https://klogs.com.tr/terms

Changelog

v0.50 (Current)

✅ Recurring payments support
✅ Payment order feature
✅ Webhook notifications
✅ Flexible period management

Next Steps

Learn how to create Card Owner Registration
Review how to set up Recurring Payment
Complete Webhook integration
Test in the test environment
Go live! 🚀

💡 Tip: Before getting started, familiarize yourself with the API by testing with test cards. Check out the Test Cards section.

💳 Registered Payment API ​

Overview ​

Features ​

API Version ​

Base URL ​

Test Environment ​

Production Environment ​

Authentication ​

Quick Start ​

1️⃣ Register Card Owner ​

2️⃣ Create Recurring Payment ​

3️⃣ Configure Webhook ​

API Endpoints ​

Card Owner Operations ​

Payment Order Operations ​

Recurring Payment Operations ​

Webhook Operations ​

Data Models ​

RegisteredPaymentStatus ​

RecurringPaymentFrequence ​

OrderDirection ​

Use Cases ​

Scenario 1: Monthly Subscription ​

Scenario 2: Quarterly Payment ​

Scenario 3: Annual Renewal ​

Scenario 4: One-Time Future Payment ​

Error Handling ​

Example Error Response ​

Common HTTP Codes ​

Rate Limiting ​

Security ​

Best Practices ​

PCI-DSS Compliance ​

Support and Contact ​

Technical Support ​

License ​

Terms of Service ​

Changelog ​

v0.50 (Current) ​

Next Steps ​

💳 Registered Payment API

Overview

Features

API Version

Base URL

Test Environment

Production Environment

Authentication

Quick Start

1️⃣ Register Card Owner

2️⃣ Create Recurring Payment

3️⃣ Configure Webhook

API Endpoints

Card Owner Operations

Payment Order Operations

Recurring Payment Operations

Webhook Operations

Data Models

RegisteredPaymentStatus

RecurringPaymentFrequence

OrderDirection

Use Cases

Scenario 1: Monthly Subscription

Scenario 2: Quarterly Payment

Scenario 3: Annual Renewal

Scenario 4: One-Time Future Payment

Error Handling

Example Error Response

Common HTTP Codes

Rate Limiting

Security

Best Practices

PCI-DSS Compliance

Support and Contact

Technical Support

License

Terms of Service

Changelog

v0.50 (Current)

Next Steps