PayTR.Sdk 0.9.0-alpha.1

PayTR.Sdk

PayTR.Sdk is a security-focused, strongly typed .NET SDK for PayTR APIs.

PayTR.Sdk is an independent, community-maintained .NET SDK for PayTR APIs. This project is not affiliated with, endorsed by, sponsored by, or maintained by PayTR. PayTR and related trademarks belong to their respective owners.

Installation

The package has not been published to NuGet. For local evaluation, reference src/PayTR.Sdk/PayTR.Sdk.csproj from a checkout. Once a prerelease is deliberately published, the installation command will be:

dotnet add package PayTR.Sdk --prerelease

Quick start

Keep real credentials outside source control. A single long-lived client exposes all modules:

using PayTR.Sdk;

var options = new PaytrOptions
{
    MerchantId = Environment.GetEnvironmentVariable("PAYTR_MERCHANT_ID")
        ?? throw new InvalidOperationException("Missing merchant id."),
    MerchantKey = Environment.GetEnvironmentVariable("PAYTR_MERCHANT_KEY")
        ?? throw new InvalidOperationException("Missing merchant key."),
    MerchantSalt = Environment.GetEnvironmentVariable("PAYTR_MERCHANT_SALT")
        ?? throw new InvalidOperationException("Missing merchant salt."),
};

using var paytr = new PaytrClient(options);

var result = await paytr.Iframe.CreateTokenAsync(new()
{
    UserIp = "203.0.113.10",
    MerchantOrderId = $"sdk-it-{Guid.NewGuid():N}",
    Email = "test@example.com",
    PaymentAmount = 10.25m,
    Basket = [new() { Name = "Test product", UnitPrice = 10.25m, Quantity = 1 }],
    UserName = "Test Customer",
    UserAddress = "Test Address",
    UserPhone = "05000000000",
    SuccessUrl = new("https://merchant.example/paytr/success"),
    FailureUrl = new("https://merchant.example/paytr/failure"),
    TestMode = true,
});

For ASP.NET Core, install PayTR.Sdk.AspNetCore, call services.AddPaytr(...), and use the callback request extensions plus PaytrCallbackResults.Ok(). See the ASP.NET sample.

Supported PayTR APIs

Supported is reserved for an implemented, documented, tested contract.

iFrame and Direct API security

The iFrame flow uses a PayTR-hosted payment UI and is the recommended first SDK integration. Direct API uses a merchant-designed card form. PayTR's official Direct API documentation says the form containing card data must post directly to PayTR and must not post to the merchant server.

Direct.CreatePaymentForm returns only a fixed PayTR action URL and signed, read-only hidden fields. It has no PAN, CVV, expiry, or cardholder properties. The merchant's browser form owns those inputs and posts them directly to PayTR. The ASP.NET renderer HTML-encodes hidden fields. Using a NuGet package does not by itself make an application PCI-DSS compliant.

Callback behavior

The customer's success/failure redirect is informational; it must not determine authoritative payment state. PayTR sends a separate server-to-server form callback. Applications must:

1. validate its hash;
2. find the order by merchant_oid;
3. process the terminal state exactly once in durable storage;
4. treat valid duplicate notifications as already handled; and
5. return exact plain-text OK after safe processing.

Callback signature validation does not provide database idempotency. PayTR can deliver the same order notification more than once when acknowledgement is not observed.

Failure, timeout, and retry policy

The SDK will not automatically retry payments, refunds, transfers, or other financial mutations. A timeout or cancellation can mean that the client did not receive a response even though PayTR may have processed the request. It must not be treated as confirmed payment failure or blindly replayed. Use the official status inquiry/reconciliation workflow where applicable.

Release track

• 0.2: iFrame and payment callbacks
• 0.3–0.7: inquiry, refund, Link, reports/rates/BIN, EFT and marketplace
• 0.8: card-free Direct browser forms and BKM Express
• 0.9: registered-card and recurring Non3D operations
• 1.0: API compatibility baseline after all applicable live/security gates
• 1.x: optional NeoPOS module only after an official server-side contract is available

The roadmap is not a compatibility promise. Before 1.0, every public API remains subject to semantic versioning and changelog documentation.

Documentation

• Architecture
• Official API research notes
• Security architecture
• Getting started
• iFrame and callbacks
• Transactions and refunds
• Link API
• Rates, BIN, and reports
• EFT and marketplace
• Direct and registered cards
• Security reporting policy
• Contributing
• Changelog

The official PayTR Developer Center is the source of truth for PayTR behavior. Report documentation ambiguities rather than guessing payment semantics.

Building

The repository requires the .NET 10 SDK and builds the library for .NET 8 and .NET 10.

dotnet restore PayTR.Sdk.slnx
dotnet build PayTR.Sdk.slnx --configuration Release --no-restore
dotnet test PayTR.Sdk.slnx --configuration Release --no-build
dotnet format PayTR.Sdk.slnx --verify-no-changes --no-restore
dotnet pack src/PayTR.Sdk/PayTR.Sdk.csproj --configuration Release --no-build
dotnet pack src/PayTR.Sdk.AspNetCore/PayTR.Sdk.AspNetCore.csproj --configuration Release --no-build

Default tests never contact PayTR and require no credentials.

Contributing

Read CONTRIBUTING.md before proposing a change. Protocol changes must cite the current official PayTR documentation and include deterministic tests. Security vulnerabilities must follow SECURITY.md, not public issues.

License

Licensed under the MIT License.

Disclaimer

This software is provided without warranty. Payment integrations carry financial, security, regulatory, and operational responsibilities. Merchants must independently validate their PayTR configuration, compliance obligations, and production rollout.