tr_payment_hub library

Turkish Payment Gateway Integration Library

A unified API for Turkish payment providers including iyzico and PayTR. This library provides a consistent interface for payment operations across different Turkish payment gateways.

Features

Unified API - Single interface for all supported providers
3D Secure - Full 3DS payment support for secure transactions
Installments - Query installment options by card BIN number
Refunds - Process full or partial refunds
Testing - Built-in mock provider for unit testing
Security - Automatic card masking and log sanitization

Quick Start

import 'package:tr_payment_hub/tr_payment_hub.dart';

// Create provider
final provider = TrPaymentHub.create(ProviderType.iyzico);

// Initialize with config
await provider.initialize(IyzicoConfig(
  merchantId: 'your_merchant_id',
  apiKey: 'your_api_key',
  secretKey: 'your_secret_key',
  isSandbox: true,
));

// Create payment request
final request = PaymentRequest(
  orderId: 'ORDER_123',
  amount: 100.0,
  currency: Currency.tryLira,
  card: CardInfo(
    cardHolderName: 'JOHN DOE',
    cardNumber: '5528790000000008',
    expireMonth: '12',
    expireYear: '2030',
    cvc: '123',
  ),
  buyer: BuyerInfo(
    id: 'BUYER_1',
    name: 'John',
    surname: 'Doe',
    email: 'john@example.com',
    phone: '+905551234567',
    ip: '127.0.0.1',
    city: 'Istanbul',
    country: 'Turkey',
    address: 'Test Address',
  ),
  basketItems: [
    BasketItem(
      id: 'ITEM_1',
      name: 'Product',
      category: 'Category',
      price: 100.0,
      itemType: ItemType.physical,
    ),
  ],
);

// Process payment
final result = await provider.createPayment(request);
if (result.isSuccess) {
  print('Payment successful: ${result.transactionId}');
}

Supported Providers

Provider	Non-3DS	3DS	Installments	Refunds
iyzico	Yes	Yes	Yes	Yes
PayTR	Yes	Yes	Yes	Yes

3D Secure Payments

// Initialize 3DS payment
final threeDSResult = await provider.init3DSPayment(
  request.copyWith(callbackUrl: 'https://yoursite.com/callback'),
);

if (threeDSResult.needsWebView) {
  // Display WebView with htmlContent (iyzico) or redirectUrl (PayTR)
}

// After user completes verification
final result = await provider.complete3DSPayment(
  threeDSResult.transactionId!,
  callbackData: callbackData,
);

Error Handling

All payment operations throw PaymentException on errors:

try {
  await provider.createPayment(request);
} on PaymentException catch (e) {
  print('Error: ${e.code} - ${e.message}');
}

Testing

Use MockPaymentProvider for unit testing:

final mockProvider = TrPaymentHub.createMock(shouldSucceed: true);

Security

Card numbers are automatically masked in logs
Use LogSanitizer for safe logging of payment data
Never log raw card numbers or CVV values

Classes

AddressInfo: Address information for shipping or billing.
BasketItem: Represents a single item in the shopping basket.
BuyerInfo: Buyer information for payment requests.
CardInfo: Card information for payment processing.
CircuitBreaker: Circuit breaker implementation for fault tolerance
CircuitBreakerConfig: Circuit breaker configuration
CircuitBreakerManager: Manager for multiple circuit breakers
FakeBasketItem: Generates fake BasketItem objects for testing.
FakeBuyerInfo: Generates fake BuyerInfo objects for testing.
FakeCardInfo: Generates fake CardInfo objects for testing.
FakePaymentRequest: Generates fake PaymentRequest objects for testing.
HashUtils: Hash ve şifreleme yardımcıları
InstallmentInfo: Installment information for a specific card BIN.
InstallmentOption: Single installment option with pricing details.
IyzicoConfig: iyzico için config
IyzicoProvider: iyzico Payment Provider
LogEntry: Log entry structure
LogSanitizer: Log temizleme - hassas verileri maskeler.
MockPaymentProvider: Mock payment provider for testing.
ParamConfig: Param için config
ParamProvider: Param POS Payment Provider
PaymentConfig: Temel config sınıfı
PaymentLogger: Secure payment logger with automatic sanitization
PaymentMockClient: Provider testleri için HTTP response'ları simüle eden mock client factory
PaymentProvider: Ana payment provider interface
PaymentRequest: Payment request containing all data needed to process a payment.
PaymentResult: Result of a payment transaction.
PaymentUtils: Shared utilities for payment providers.
PayTRConfig: PayTR için config
PayTRProvider: PayTR Payment Provider
RefundRequest: Request model for processing refunds.
RefundResult: Result of a refund operation.
RetryConfig: Retry configuration for payment operations
RetryHandler: Retry handler with exponential backoff and jitter
SavedCard: Represents a saved/tokenized card for recurring payments.
SipayConfig: Sipay için config
SipayProvider: Sipay Payment Provider
TestCards: Test card numbers for sandbox/development environments.
ThreeDSInitResult: Result of 3D Secure payment initialization.
TrPaymentHub: TR Payment Hub - Ana Factory Sınıfı

Enums

CardAssociation: Kart şeması
CardType: Kart tipleri
CircuitState: Circuit breaker states
Currency: Para birimleri
ItemType: Ürün tipi
LogLevel: Log level enumeration
MockErrorScenario: Simulated error scenarios for testing.
PaymentStatus: Ödeme durumu
ProviderType: Desteklenen ödeme sağlayıcıları
ThreeDSStatus: 3DS durumu

Extensions

PaymentConfigProductionValidation on PaymentConfig: Production validation utilities for payment configurations.
RetryExtension on Future<T>: Extension for adding retry capability to futures

Typedefs

LogCallback = void Function(LogEntry entry): Callback type for log handlers
RetryCallback = void Function(int attempt, Object error, Duration delay): Callback type for retry events

Exceptions / Errors

CircuitBreakerOpenException: Exception thrown when circuit breaker is open
PaymentException: Ödeme hatası.
ValidationException: Input validation exception - thrown when validation fails

tr_payment_hub library

Features

Quick Start

Supported Providers

3D Secure Payments

Error Handling

Testing

Security

Classes

Enums

Extensions

Typedefs

Exceptions / Errors

tr_payment_hub package

tr_payment_hub library