---
title: "PayTR Proje Dokümanı"
canonical: https://hamzadenizyilmaz.com.tr/dokumanlar/github-paytr
author: "Hamza Deniz Y\u0131lmaz"
created: 2026-08-26T17:50:45.0000000+00:00
---

# PayTR Proje Dokümanı

## Proje özeti

Community PayTR SDK for ASP.NET Core (.NET 10) and Node.js with payment APIs, callbacks, refunds, recurring payments, reporting, OpenAPI and security-focused integration.

| Alan | GitHub bilgisi |
|---|---|
| Depo | [hamzadenizyilmaz/PayTR](https://github.com/hamzadenizyilmaz/PayTR) |
| Ana dil | Belirtilmemiş |
| Varsayılan dal | `main` |
| Lisans | GPL-3.0 |
| Oluşturulma | 2026-08-26 |
| Son kaynak güncellemesi | 2026-08-26 |

## Proje README belgesi

# PayTR Enterprise SDK

### Production-oriented PayTR integration for ASP.NET Core 10 and Node.js 20+

A security-focused, server-side PayTR integration toolkit with runnable API applications, callback verification, financial-operation safeguards, health checks, OpenAPI documentation, SQL Server reference persistence, and CI quality gates.

  
  
  

  
  
  
  
  

  
  
  
  

**Current release:** `2.5.0`  
**Runtimes:** `.NET 10 / ASP.NET Core 10` and `Node.js 20+`  
**Payment provider:** [PayTR](https://www.paytr.com/)  
**Official provider documentation:** [dev.paytr.com](https://dev.paytr.com/)
---
## Table of contents

- [Overview](#overview)
- [Project status](#project-status)
- [What this project provides](#what-this-project-provides)
- [Supported PayTR capabilities](#supported-paytr-capabilities)
- [Engineering principles](#engineering-principles)
- [Runtime matrix](#runtime-matrix)
- [Requirements](#requirements)
- [Quick start](#quick-start)
  - [ASP.NET Core](#aspnet-core)
  - [Node.js](#nodejs)
- [Configuration](#configuration)
  - [ASP.NET configuration](#aspnet-configuration)
  - [Node.js configuration](#nodejs-configuration)
  - [Configuration precedence](#configuration-precedence)
  - [Production secret management](#production-secret-management)
- [Authentication and authorization](#authentication-and-authorization)
- [API surface](#api-surface)
- [Payment flow](#payment-flow)
- [Callback processing](#callback-processing)
- [Direct API and card-data boundary](#direct-api-and-card-data-boundary)
- [Refund and financial mutation safety](#refund-and-financial-mutation-safety)
- [Stored cards and recurring payments](#stored-cards-and-recurring-payments)
- [Link API](#link-api)
- [Platform and returned transfers](#platform-and-returned-transfers)
- [Reporting](#reporting)
- [Persistence and idempotency](#persistence-and-idempotency)
- [Background reconciliation](#background-reconciliation)
- [Health checks](#health-checks)
- [Observability](#observability)
- [Security controls](#security-controls)
- [OpenAPI and Postman](#openapi-and-postman)
- [SQL Server reference schema](#sql-server-reference-schema)
- [Reverse proxy and HTTPS](#reverse-proxy-and-https)
- [Testing and quality gates](#testing-and-quality-gates)
- [CI and static analysis](#ci-and-static-analysis)
- [Troubleshooting](#troubleshooting)
- [Versioning](#versioning)
- [Security policy](#security-policy)
- [Contributing](#contributing)
- [License](#license)
- [Provider responsibility notice](#provider-responsibility-notice)
---
## Overview

PayTR Enterprise SDK is an independent server-side integration project that organizes PayTR payment operations into a reusable, auditable, and production-oriented backend layer for ASP.NET Core and Node.js applications.

The project intentionally goes beyond a minimal request example. It includes application-level controls required around payment integrations: input validation, HMAC signing, callback verification, internal API authorization, rate limiting, CORS policy, request-size limits, correlation IDs, health checks, reconciliation primitives, example persistence models, operational documentation, and deployment assets.

Two implementation families are maintained:

| Runtime | Primary application | Runnable example | Configuration | Hosting model |
|---|---|---|---|---|
| ASP.NET Core | `PayTR` | `PayTRExample` | `appsettings*.json` + standard ASP.NET environment overrides | Kestrel / IIS / reverse proxy |
| Node.js | `PayTR` | `PayTRExample` | `appsettings*.json` + explicit environment-variable overrides | Native Node.js HTTP server / reverse proxy |

The primary applications contain the project code and the PayTR integration layer. The example applications are designed to be runnable references for local integration testing and application wiring.

> [!IMPORTANT]
> This repository is an independent integration toolkit. It is **not an official PayTR SDK**. Provider-side permissions, field requirements, endpoints, callback semantics, commercial conditions, and merchant-account capabilities must always be validated against the current PayTR documentation and the merchant account before production rollout.

> [!CAUTION]
> Payment systems are financial systems. Never treat a redirect page, browser response, or client-side state as final payment confirmation. Final order state must be driven by an authenticated server-to-server provider callback and an idempotent business transition.
---
## Project status

The current repository release is `2.5.0`.

The Node.js applications include automated tests and syntax-oriented quality scripts. The repository also includes GitHub Actions definitions for Node.js, .NET, and CodeQL-oriented analysis.

For production release decisions, use **your own CI results from the exact commit you intend to deploy**. Do not rely on README text as build evidence.

A complete release should require, at minimum:

- clean dependency restore;
- successful compilation/build;
- automated test success;
- security/static-analysis review;
- provider callback verification in a non-production environment;
- a successful end-to-end payment scenario using approved test settings;
- confirmation that no secrets are committed;
- confirmation that production feature flags match PayTR merchant permissions;
- explicit rollback and reconciliation procedures.
---
## What this project provides

### Server-side integration layer

The project centralizes provider-facing behavior such as:

- credential loading;
- request validation;
- request signing;
- callback signature verification;
- PayTR HTTP calls;
- provider-response handling;
- payment status lookup;
- refund requests;
- link operations;
- stored-card operations;
- recurring payment requests;
- transfer workflows;
- reporting requests.

### Runnable APIs

Both runtime families expose runnable HTTP APIs for integration testing and reference hosting. Their public server-side responsibilities include:

- provider operations behind an internal API key;
- PayTR callback endpoints;
- readiness and liveness endpoints;
- safe configuration-status output;
- reconciliation queue entry points where implemented.

### Operational baseline

The repository also includes:

- OpenAPI `3.1` contract assets;
- Postman collection assets;
- SQL Server reference persistence objects;
- GitHub Actions workflows;
- security policy;
- contribution policy;
- detailed changelog;
- production-oriented documentation.
---
## Supported PayTR capabilities

The codebase exposes integration support for the following PayTR-oriented workflows.

### Checkout

- iFrame token creation;
- iFrame V2-compatible options exposed by the implementation;
- Havale / EFT iFrame token creation;
- Direct API signed form-field generation;
- BKM Express signed form-field generation behind a feature gate.

### Payment lifecycle

- payment-result callback verification;
- merchant-order payment-status query;
- full refund requests;
- partial refund requests;
- reconciliation queueing.

### Link API

- payment-link creation;
- link deletion;
- link delivery by SMS;
- link delivery by email;
- Link API callback verification.

### Stored-card and recurring operations

- stored-card listing by user token;
- stored-card deletion;
- recurring payment requests using provider-issued card tokens.

### Card metadata

- BIN lookup;
- installment-rate lookup.

### Platform operations

- platform transfer request;
- platform transfer callback verification;
- returned-transfer list operation;
- returned-transfer send operation;
- returned-transfer callback verification.

### Reports

- transaction statement;
- payment summary;
- payment detail.

> [!NOTE]
> A locally exposed operation does not prove that the corresponding PayTR capability is enabled for a merchant. Some services require account-specific authorization or commercial enablement.
---
## Engineering principles

### 1. Secrets stay on trusted servers

`merchant_id`, `merchant_key`, `merchant_salt`, production internal API keys, access tokens, PAN, CVV/CVC, and comparable sensitive data must never be embedded in frontend code or public repositories.

### 2. Callback verification precedes business mutation

No callback should change payment, order, transfer, or refund state until its signature has been validated.

### 3. Callbacks are treated as repeatable delivery

Provider callbacks can be delivered more than once. Business transitions must therefore be idempotent.

### 4. Financial mutations are not blindly retried

Refunds, transfers, and other money-changing operations may create ambiguous outcomes when network failures occur after the provider accepted a request. Reconciliation and status lookup are safer than automatic repetition.

### 5. High-risk capabilities are feature-gated

Direct API and BKM Express support are disabled by default in the application configuration.

### 6. Runtime behavior is explicit

The project uses explicit configuration files, explicit environment overrides, bounded request sizes, bounded timeouts, and named health endpoints.

### 7. Error responses do not reveal secrets

API errors are normalized and should not expose merchant credentials, provider tokens, stack traces, or cardholder data.
---
## Runtime matrix

| Capability | ASP.NET Core | Node.js |
|---|---:|---:|
| Target/runtime | `.NET 10` | `Node.js >=20` |
| Primary API application | Yes | Yes |
| Runnable example application | Yes | Yes |
| HMAC-SHA256 signing | Yes | Yes |
| Constant-time hash comparison | Yes | Yes |
| JSON appsettings | Yes | Yes |
| Environment overrides | ASP.NET configuration providers | Explicit environment mapping |
| Internal API key | Yes | Yes |
| Rate limiting | Yes | Yes |
| Request-size limit | Yes | Yes |
| Correlation IDs | Yes | Yes |
| Security headers | Yes | Yes |
| CORS allowlist | Yes | Yes |
| Liveness endpoint | Yes | Yes |
| Readiness endpoint | Yes | Yes |
| Reconciliation worker/loop | Yes | Yes |
| Automated tests in repository | Runtime-dependent | Yes |
---
## Requirements

### ASP.NET Core

Required:

- .NET SDK compatible with target framework `net10.0`;
- an operating system supported by the selected .NET runtime;
- outbound HTTPS access to PayTR;
- valid PayTR merchant credentials for provider-connected requests.

Useful tools:

- Visual Studio with .NET 10 support;
- Visual Studio Code with C# tooling;
- `curl`, Postman, or an HTTP client;
- SQL Server if adopting the reference persistence model.

Check your SDK:

```bash
dotnet --version
```

### Node.js

Required:

- Node.js `20` or newer;
- npm compatible with the selected Node.js version;
- outbound HTTPS access to PayTR;
- valid PayTR merchant credentials for provider-connected requests.

Check your runtime:

```bash
node --version
npm --version
```

### PayTR merchant account

Before production enablement, confirm:

- merchant credentials are active;
- notification/callback URL configuration is correct;
- required service permissions are enabled;
- Direct API permission is enabled before turning on Direct API locally;
- Non3D permission exists before using recurring flows that require it;
- transfer/reporting services are available to the merchant account;
- production URLs use the correct scheme and certificate configuration.
---
# Quick start

## ASP.NET Core

### Primary application

Restore:

```bash
dotnet restore ASP.NET/PayTR/PayTR.sln
```

Build:

```bash
dotnet build ASP.NET/PayTR/PayTR.sln -c Release
```

Run:

```bash
dotnet run --project ASP.NET/PayTR/PayTR/PayTR.csproj
```

Default development URLs are defined in the project's `launchSettings.json` and include:

- `http://localhost:5080`
- `https://localhost:7080`

Health checks:

```bash
curl http://localhost:5080/health/live
curl http://localhost:5080/health/ready
```

### Example application

Restore:

```bash
dotnet restore ASP.NET/PayTRExample/PayTRExample.sln
```

Build:

```bash
dotnet build ASP.NET/PayTRExample/PayTRExample.sln -c Release
```

Run:

```bash
dotnet run --project ASP.NET/PayTRExample/PayTRExample/PayTRExample.csproj
```

Default development URLs include:

- `http://localhost:5180`
- `https://localhost:7180`

Health checks:

```bash
curl http://localhost:5180/health/live
curl http://localhost:5180/health/ready
```

### Development internal API key

The development configuration includes a local-only internal API key:

```text
paytr-local-development-key
```

Use it only for local development. Never copy this value into a production deployment.

Example:

```bash
curl   -H "X-Internal-Api-Key: paytr-local-development-key"   http://localhost:5080/api/v1/system/configuration
```

## Node.js

No external runtime dependencies are required by the current application packages.

### Primary application

```bash
cd NodeJS/PayTR
npm test
npm run lint
npm run build
npm start
```

Default port:

```text
3100
```

Health checks:

```bash
curl http://localhost:3100/health/live
curl http://localhost:3100/health/ready
```

### Example application

```bash
cd NodeJS/PayTRExample
npm test
npm run lint
npm run build
npm start
```

Default port:

```text
3200
```

Health checks:

```bash
curl http://localhost:3200/health/live
curl http://localhost:3200/health/ready
```

### Select environment

Node.js reads `NODE_ENV` and then merges the matching `appsettings..json` file over `appsettings.json`.

Examples:

```bash
NODE_ENV=Development npm start
```

```bash
NODE_ENV=Production npm start
```
---
# Configuration

## ASP.NET configuration

The ASP.NET applications bind three main sections.

### `PayTR`

| Setting | Purpose | Production guidance |
|---|---|---|
| `MerchantId` | PayTR merchant identifier | Supply through a secret-aware configuration provider |
| `MerchantKey` | PayTR merchant key | Secret; never commit a real value |
| `MerchantSalt` | PayTR merchant salt | Secret; never commit a real value |
| `BaseUri` | PayTR base URI | Keep on official HTTPS provider endpoint unless explicitly testing a controlled substitute |
| `Timeout` | Outbound HTTP timeout | Keep bounded; default is 20 seconds |

### `Security`

| Setting | Purpose | Default posture |
|---|---|---|
| `InternalApiKey` | Protects `/api/v1/paytr` and `/api/v1/system` | Empty outside development until supplied securely |
| `AllowedOrigins` | CORS allowlist | Empty in production template |
| `DirectApiEnabled` | Enables Direct API wrapper routes | `false` |
| `BkmExpressEnabled` | Enables BKM Express wrapper route | `false` |
| `RateLimitPerMinute` | Per-client fixed-window request limit | `120` |
| `MaxRequestBodyBytes` | Maximum request body size | `65536` |

### `BackgroundJobs`

| Setting | Purpose | Default |
|---|---|---|
| `ReconciliationEnabled` | Enables background reconciliation processing | `false` in base configuration |
| `Interval` | Worker interval | `00:05:00` |

### Production environment variables

ASP.NET Core supports hierarchical environment-variable overrides using double underscores.

Examples:

```bash
PayTR__MerchantId=...
PayTR__MerchantKey=...
PayTR__MerchantSalt=...
Security__InternalApiKey=...
Security__DirectApiEnabled=false
Security__BkmExpressEnabled=false
BackgroundJobs__ReconciliationEnabled=true
```

Do not commit real values to `appsettings.json` or `appsettings.Production.json`.

## Node.js configuration

The Node.js configuration loader supports JSON appsettings plus explicit environment-variable overrides.

| Environment variable | Maps to | Notes |
|---|---|---|
| `NODE_ENV` | runtime environment | Defaults to `Development` |
| `PORT` | server port | Valid range `1..65535` |
| `PAYTR_MERCHANT_ID` | merchant ID | Secret-adjacent merchant configuration |
| `PAYTR_MERCHANT_KEY` | merchant key | Secret |
| `PAYTR_MERCHANT_SALT` | merchant salt | Secret |
| `PAYTR_BASE_URL` | provider base URL | Defaults to `https://www.paytr.com` |
| `PAYTR_TIMEOUT_MS` | provider timeout | Valid range `1..120000` |
| `INTERNAL_API_KEY` | internal wrapper API key | Secret |
| `ALLOWED_ORIGINS` | CORS allowlist | Comma-separated |
| `PAYTR_DIRECT_API_ENABLED` | Direct API feature flag | Boolean |
| `PAYTR_BKM_EXPRESS_ENABLED` | BKM Express feature flag | Boolean |
| `PAYTR_RECONCILIATION_ENABLED` | reconciliation flag | Boolean |
| `PAYTR_RECONCILIATION_INTERVAL_MS` | reconciliation interval | `10000..86400000` |
| `PAYTR_RATE_LIMIT_PER_MINUTE` | request rate limit | `1..10000` |
| `PAYTR_MAX_BODY_BYTES` | request body limit | `1024..1048576` |

Example production shell configuration:

```bash
export NODE_ENV=Production
export PORT=3100
export PAYTR_MERCHANT_ID="..."
export PAYTR_MERCHANT_KEY="..."
export PAYTR_MERCHANT_SALT="..."
export INTERNAL_API_KEY="..."
export ALLOWED_ORIGINS="https://example.com"
export PAYTR_DIRECT_API_ENABLED=false
export PAYTR_BKM_EXPRESS_ENABLED=false
npm start
```

## Configuration precedence

### ASP.NET Core

Use standard ASP.NET Core configuration precedence. Environment variables and secret-aware providers should override committed JSON values in production.

### Node.js

The effective configuration follows this model:

1. `appsettings.json`;
2. `appsettings..json`;
3. supported environment-variable overrides.

This allows development defaults without requiring tracked `.env` files.

## Production secret management

Recommended secret sources include:

- platform-native secret stores;
- managed platform secret stores;
- operating-system environment injection;
- Azure Key Vault, AWS Secrets Manager, Google Secret Manager, HashiCorp Vault, or equivalent managed systems;
- encrypted deployment variables supplied by CI/CD.

Never:

- commit real merchant keys;
- place secrets in frontend JavaScript;
- paste secrets into issue trackers;
- write secrets to logs;
- persist CVV/CVC;
- include production secrets in screenshots or support tickets.
---
# Authentication and authorization

The application-facing provider routes are protected by an internal API key header:

```http
X-Internal-Api-Key: 
```

Protected route groups include:

- `/api/v1/paytr/*`
- `/api/v1/system/*`

PayTR callback routes are intentionally not protected by the internal API key because they must be callable by PayTR. Their trust boundary is the provider signature verification logic.

> [!IMPORTANT]
> The internal API key mechanism is an integration boundary, not a substitute for a complete product authentication and authorization model. If the wrapper is exposed to multiple applications, users, tenants, or administrative roles, place it behind your real identity, authorization, network, and service-to-service controls.

Recommended production controls:

- private network exposure where possible;
- gateway/service-mesh authentication;
- workload identity or mTLS for service-to-service traffic;
- secret rotation;
- least-privilege network rules;
- request auditing that excludes sensitive payloads.
---
# API surface

The following routes represent the current wrapper/application surface.

## System and health

| Method | Route | Authentication | Purpose |
|---|---|---|---|
| `GET` | `/` | No | Service metadata/root response |
| `GET` | `/health/live` | No | Process liveness |
| `GET` | `/health/ready` | No | Configuration/readiness state |
| `GET` | `/api/v1/system/configuration` | Internal API key | Safe configuration-status view |

Node.js also exposes system callback/reconciliation inspection routes implemented by its router. Treat these as administrative/internal surfaces and keep them protected.

## PayTR operations

| Method | Route | Purpose |
|---|---|---|
| `POST` | `/api/v1/paytr/iframe/token` | Create iFrame token |
| `POST` | `/api/v1/paytr/eft/iframe/token` | Create Havale/EFT iFrame token |
| `POST` | `/api/v1/paytr/direct/form-fields` | Build signed Direct API form fields |
| `POST` | `/api/v1/paytr/direct/bkm-express/form-fields` | Build signed BKM Express fields |
| `POST` | `/api/v1/paytr/direct/recurring` | Submit recurring payment request |
| `POST` | `/api/v1/paytr/status` | Query payment status |
| `POST` | `/api/v1/paytr/refunds` | Request full/partial refund |
| `POST` | `/api/v1/paytr/bin` | BIN lookup |
| `POST` | `/api/v1/paytr/installments` | Installment-rate lookup |
| `POST` | `/api/v1/paytr/links` | Create payment link |
| `DELETE` | `/api/v1/paytr/links/{id}` | Delete payment link |
| `POST` | `/api/v1/paytr/links/sms` | Send payment link by SMS |
| `POST` | `/api/v1/paytr/links/email` | Send payment link by email |
| `POST` | `/api/v1/paytr/cards/list` | List stored cards |
| `DELETE` | `/api/v1/paytr/cards` | Delete stored card |
| `POST` | `/api/v1/paytr/platform/transfers` | Create platform transfer |
| `POST` | `/api/v1/paytr/returned-transfers/list` | List returned transfers |
| `POST` | `/api/v1/paytr/returned-transfers/send` | Send returned transfer |
| `POST` | `/api/v1/paytr/reports/transactions` | Transaction statement |
| `POST` | `/api/v1/paytr/reports/payment-summary` | Payment summary |
| `POST` | `/api/v1/paytr/reports/payment-detail` | Payment detail |
| `POST` | `/api/v1/paytr/reconciliation/enqueue` | Enqueue reconciliation work |

All `/api/v1/paytr/*` routes require the internal API key in the current application implementation.

## Provider callbacks

| Method | Route | Internal API key | Trust mechanism |
|---|---|---:|---|
| `POST` | `/api/v1/callbacks/paytr/payment` | No | PayTR callback signature verification |
| `POST` | `/api/v1/callbacks/paytr/link` | No | Link callback hash verification |
| `POST` | `/api/v1/callbacks/paytr/platform-transfer` | No | Platform-transfer callback hash verification |
| `POST` | `/api/v1/callbacks/paytr/returned-transfer` | No | Returned-transfer callback hash verification |

Provider callbacks must remain reachable from PayTR while still being protected by signature validation, rate controls appropriate to your topology, and idempotent persistence.
---
# Payment flow

A safe iFrame-oriented payment lifecycle should be modeled as follows.

1. Your application creates an internal order record.
2. Your backend assigns a unique merchant order identifier.
3. Your backend validates price, customer, basket, callback/redirect, and merchant input.
4. Your backend requests an iFrame token from PayTR.
5. The frontend opens the PayTR-hosted payment interface using the returned token.
6. Browser navigation to success/failure pages is treated as user experience only.
7. PayTR sends the server-to-server result to the configured notification URL.
8. Your callback endpoint verifies the received hash.
9. Your persistence layer atomically checks idempotency and applies the allowed state transition.
10. Your endpoint returns the provider-required acknowledgement only after accepted processing.
11. Any ambiguous state is reconciled through status-query/reporting logic rather than guessed from client behavior.

PayTR documents iFrame integration as a two-step process: server-side token acquisition followed by a separately implemented callback/notification endpoint. The callback is the authoritative server-side integration point.
---
# Callback processing

## Required callback guarantees

A production callback handler should guarantee all of the following:

- public reachability from PayTR;
- no end-user session dependency;
- exact provider signature verification;
- constant-time comparison where applicable;
- deterministic extraction of the merchant order identifier;
- idempotent callback persistence;
- atomic payment/order transition;
- no duplicate fulfillment;
- no sensitive payload logging;
- bounded execution time;
- correct provider acknowledgement;
- durable operational audit data that does not include secrets.

## Recommended callback transaction

Conceptually:

```text
receive callback
  -> parse bounded form payload
  -> verify provider hash
  -> reject invalid hash
  -> begin database transaction
  -> insert callback receipt using a unique idempotency key
  -> if duplicate: return prior accepted outcome
  -> load internal payment/order by merchant
```

> README içeriğinin devamı için GitHub deposundaki güncel belgeyi açın.

## Kaynak ve doğrulama

- [GitHub deposunu açın](https://github.com/hamzadenizyilmaz/PayTR)
- [README dosyasının ham sürümü](https://raw.githubusercontent.com/hamzadenizyilmaz/PayTR/main/README.md)
- [Kaynak kodu ZIP olarak indirin](https://github.com/hamzadenizyilmaz/PayTR/archive/refs/heads/main.zip)

Bu sayfadaki depo tarihleri ve teknik metadata GitHub public API kaydından alınmıştır. İçeriğin otoritatif ve en güncel sürümü GitHub deposudur.

## PayTR Proje Dokümanı — kaynak ve uygulama notları

### Proje ve belgeyi birlikte değerlendirin

Bu kayıt için kaynak açıklama korunmuştur. Kurulum, bağımlılık ve lisans kararlarında bu kayda bağlı proje ve dokümanı birlikte inceleyin; doğrulanmamış sürüm, ölçüm veya özellik bu ekle ilan edilmemiştir.

### Metinde geçen depo bağlantıları

- [Depo bağlantısı](https://github.com/hamzadenizyilmaz/PayTR)

### İlgili okuma yolu

- [AspNetRestKit Proje Dokümanı](/dokumanlar/github-aspnetrestkit)

- [BoostCore-Module Proje Dokümanı](/dokumanlar/github-boostcore-module)

- [Creart-Backup-and-Management-Software Proje Dokümanı](/dokumanlar/github-creart-backup-and-management-software)