---
## 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.
Sponsored by Bilhost
Infrastructure sponsorship and project support provided by Bilhost Bilişim Teknolojileri A.Ş.
