PayTR Proje Dokümanı

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.

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
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 Official provider documentation: dev.paytr.com

Overview
Project status
What this project provides
Supported PayTR capabilities
Engineering principles
Runtime matrix
Requirements
Quick start
- ASP.NET Core
- Node.js
Configuration
- ASP.NET configuration
- Node.js configuration
- Configuration precedence
- Production secret management
Authentication and authorization
API surface
Payment flow
Callback processing
Direct API and card-data boundary
Refund and financial mutation safety
Stored cards and recurring payments
Link API
Platform and returned transfers
Reporting
Persistence and idempotency
Background reconciliation
Health checks
Observability
Security controls
OpenAPI and Postman
SQL Server reference schema
Reverse proxy and HTTPS
Testing and quality gates
CI and static analysis
Troubleshooting
Versioning
Security policy
Contributing
License
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:

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:

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:

dotnet restore ASP.NET/PayTR/PayTR.sln

Build:

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

Run:

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:

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

Example application

Restore:

dotnet restore ASP.NET/PayTRExample/PayTRExample.sln

Build:

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

Run:

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

Default development URLs include:

http://localhost:5180
https://localhost:7180

Health checks:

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:

paytr-local-development-key

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

Example:

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

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

Default port:

Health checks:

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

Example application

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

Default port:

Health checks:

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:

NODE_ENV=Development npm start

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:

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:

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:

appsettings.json;
appsettings..json;
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:

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.

Your application creates an internal order record.
Your backend assigns a unique merchant order identifier.
Your backend validates price, customer, basket, callback/redirect, and merchant input.
Your backend requests an iFrame token from PayTR.
The frontend opens the PayTR-hosted payment interface using the returned token.
Browser navigation to success/failure pages is treated as user experience only.
PayTR sends the server-to-server result to the configured notification URL.
Your callback endpoint verifies the received hash.
Your persistence layer atomically checks idempotency and applies the allowed state transition.
Your endpoint returns the provider-required acknowledgement only after accepted processing.
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:

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

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ı

Proje özeti

Proje README belgesi

PayTR Enterprise SDK

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

Current release: 2.5.0 Runtimes: .NET 10 / ASP.NET Core 10 and Node.js 20+ Payment provider: PayTR Official provider documentation: dev.paytr.com

Table of contents

Overview

Project status

What this project provides

Server-side integration layer

Runnable APIs

Operational baseline

Supported PayTR capabilities

Checkout

Payment lifecycle

Link API

Stored-card and recurring operations

Card metadata

Platform operations

Reports

Engineering principles

1. Secrets stay on trusted servers

2. Callback verification precedes business mutation

3. Callbacks are treated as repeatable delivery

4. Financial mutations are not blindly retried

5. High-risk capabilities are feature-gated

6. Runtime behavior is explicit

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

Requirements

ASP.NET Core

Node.js

PayTR merchant account

Quick start

ASP.NET Core

Primary application

Example application

Development internal API key

Node.js

Primary application

Example application

Select environment

Configuration

ASP.NET configuration

PayTR

Security

BackgroundJobs

Production environment variables

Node.js configuration

Configuration precedence

ASP.NET Core

Node.js

Production secret management

Authentication and authorization

API surface

System and health

PayTR operations

Provider callbacks

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

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

Recommended callback transaction

Kaynak ve doğrulama

Current release: `2.5.0` Runtimes: `.NET 10 / ASP.NET Core 10` and `Node.js 20+` Payment provider: PayTR Official provider documentation: dev.paytr.com

`PayTR`

`Security`

`BackgroundJobs`