📋 Create Payment Order

Endpoint

POST /paymentOrder

Description

Creates a payment order to be executed on a specific date. This operation schedules a one-time payment for a registered card owner in the future. The payment order is automatically processed on the specified date.

Headers

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

Request: PaymentOrderRequest

{
  "reference": "ORDER-2026-001",
  "amount": 150.50,
  "currencyCode": "TRY",
  "paymentSystemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "explanation": "Subscription fee - February 2026",
  "ownerDescription": {
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+905551234567",
    "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "paymentChannel": "web",
  "paymentTime": "2026-02-28T09:00:00Z"
}

Parameters

Parameter	Type	Required	Description
reference	string	✅	Order reference code (max 150 characters)
amount	number	✅	Payment amount (decimal number)
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)
paymentTime	datetime	✅	Date and time when payment will be executed (ISO 8601)

OwnerDescription Parameters

Parameter	Type	Required	Description
fullName	string	✅	Card owner's full name (max 100 characters)
email	string	❌	Email address
phone	string	✅	Phone number (E.164 format)
cardId	uuid	✅	Registered card ID

Response

Successful Request (200 OK)

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

Response Parameters

Parameter	Type	Description
success	boolean	Operation success status
error	object	Error information (if any)
shouldBeOwnerConfirmation	boolean	Is card owner confirmation required?
ownerId	string	Card owner ID
orderStatus	string	Payment order status

OrderStatus Values

Value	Description
active	Active - will be processed when payment time arrives
disabled	Disabled
complete	Completed
waitForOwnerConfirmation	Waiting for card owner confirmation
waitForCardSave	Waiting for card save

Error Codes

HTTP Code	Description
200	Operation successful
400	Invalid request (parameter errors)
401	Unauthorized access
403	Access denied

Example Usage

cURL

curl -X POST https://pgw.klogs.io/paymentOrder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORDER-2026-001",
    "amount": 150.50,
    "currencyCode": "TRY",
    "explanation": "Subscription fee - February 2026",
    "ownerDescription": {
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+905551234567",
      "cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "paymentChannel": "web",
    "paymentTime": "2026-02-28T09:00:00Z"
  }'

JavaScript

const response = await fetch('https://pgw.klogs.io/paymentOrder', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'ORDER-2026-001',
    amount: 150.50,
    currencyCode: 'TRY',
    explanation: 'Subscription fee - February 2026',
    ownerDescription: {
      fullName: 'John Doe',
      email: 'john.doe@example.com',
      phone: '+905551234567',
      cardId: '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    },
    paymentChannel: 'web',
    paymentTime: '2026-02-28T09:00:00Z'
  })
});

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

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

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

var request = new {
    reference = "ORDER-2026-001",
    amount = 150.50,
    currencyCode = "TRY",
    explanation = "Subscription fee - February 2026",
    ownerDescription = new {
        fullName = "John Doe",
        email = "john.doe@example.com",
        phone = "+905551234567",
        cardId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    paymentChannel = "web",
    paymentTime = "2026-02-28T09:00:00Z"
};

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

var response = await client.PostAsync("https://pgw.klogs.io/paymentOrder", content);
var result = await response.Content.ReadAsStringAsync();

Notes

• paymentTime must be a future date
• cardId must be a previously registered card ID
• reference should be unique for each payment order
• The payment order will be automatically executed on the specified date
• There is a retry mechanism for failed payments
• Payment results are notified via webhook

Related Endpoints

• Card Owner Registration
• Create Recurring Payment
• Webhook Operations