Terminoloji ve Kısa Notlar
HSRC Pay dokümanlarında geçen payment orchestration, routing, adapter ve webhook terimleri için hızlı sözlük.
Bu sayfa HSRC Pay dokümanlarında geçen kavramları kısa ve tutarlı şekilde tanımlar. Amaç developer, merchant ve operasyon ekiplerinin aynı kelimelerle aynı domain modelini anlamasıdır.
| Terim | Tanım |
|---|
| Payment | Merchant'ın müşteriden almak istediği ödeme niyeti veya iş seviyesindeki ödeme kaydıdır. Payment oluşturmak her zaman para çekmek anlamına gelmez. |
| Charge | Provider/rail seviyesindeki işlem denemesi, authorization veya finansal hareket temsilidir. Bir Payment birden fazla Charge attempt üretebilir. |
| Confirm | Payment'ı provider execution sürecine taşıyan kontrollü adımdır. Payment method, payer identity, routing plan ve isteğe bağlı routing_strategy bu aşamada devreye girer. |
| Capture | Ön otorizasyon sonrası tutarı kesinleştirme işlemidir. Auto-capture kapalı akışlarda ayrı operasyon olarak ele alınır. |
| Refund | Başarılı capture veya ödeme sonrası iade işlemidir. Genellikle Charge bağlamında izlenir. |
| Void | Capture edilmemiş authorization'ı iptal etme işlemidir. Refund ile karıştırılmamalıdır. |
| Resume / 3DS callback | Provider challenge sonrası gateway three-d-secure-callback-urls/:chargeId üzerinden tetiklenen devam adımıdır (resumeThreeDSecure). |
| Terim | Tanım |
|---|
| Payment Method | Kullanıcının ödeme yaptığı yöntem veya kanaldır: card, wallet, bank transfer, local method veya alternative method. Provider ile karıştırılmamalıdır. |
| Provider | Ödemeyi işleyen banka, PSP, wallet provider, sandbox provider veya internal/simulated provider'dır. |
| Provider Method | Provider'ın desteklediği payment method, network, category ve type bağlamını temsil eder. |
| Provider config | Hesaba bağlı sağlayıcı ayarı; confirm routing aday havuzunun parçasıdır. |
| Provider adapter | Sağlayıcıya özel pay, capture, refund ve 3DS resume implementasyonudur. |
| Confirm orchestrator | Routing adaylarını dener, adapter sonucunu confirmResult ve Payment/Charge status'e yazar. |
routing_strategy | Confirm body alanı: payment_provider_config_id veya provider_identifier ile aday daraltma (API adı böyledir; ayrı bir "Strategy Execution" adımı yoktur). |
| Routing | Provider seçimi, fallback, failover, capability matching ve policy/rule bazlı karar sürecidir. |
| Routing Plan | Confirm sırasında denenebilecek provider candidate'larını ve sıralamasını gösteren plandır. |
| Fallback | İlk route uygun değilse veya retryable sonuç üretirse alternatif provider/route denemesidir. |
| Normalized Result | Adapter kind (success, requires_action, declined, error) ile Payment status (SUCCEEDED, REQUIRES_ACTION, REQUIRES_PAYMENT_METHOD, vb.) eşlemesidir. |
| Terim | Tanım |
|---|
| Checkout Session | Hosted veya semi-hosted ödeme deneyimini yöneten oturumdur. Kullanıcıdan payment method ve checkout bağlamı toplanır. |
| Hosted Checkout | Ödeme formu ve bazı flow handling sorumluluklarının HSRC Pay checkout deneyimi içinde yürütüldüğü modeldir. |
| API-only Flow | Merchant'ın kendi frontend ve backend'iyle payment method topladığı, requires_action ve webhook handling'i doğrudan yönettiği modeldir. |
| Return URL | Kullanıcı deneyimini merchant ekranına geri taşıyan URL'dir. Nihai ödeme kanıtı değildir. |
| Cancel URL | Kullanıcı checkout flow'u iptal ettiğinde dönebileceği URL'dir. |
| Terim | Tanım |
|---|
| Sandbox Network | Gerçek para hareketi yapmayan, payment lifecycle ve provider davranışlarını simüle eden test ağıdır. |
| Sandbox Card | Sandbox ortamında kart allowlist validasyonu için kullanılan test kart verisidir. secure_mode: true ile geçerli sandbox kartı 3DS simulation akışına girebilir. Gerçek ödeme aracı değildir ve issuer-specific error tetiklemez. |
| Sandbox Issuer Resolution | Issuer, network, country, IIN, brand ve card type alanlarını payment method üzerinde saklayan sandbox-only kart prefix resolution’dır. Issuer behavior simulation engine değildir. |
| Sandbox Provider | Test ve geliştirme amacıyla provider behavior simülasyonu yapan provider modelidir. Production provider yerine geçmez. |
| Production | Gerçek provider credential'ları, gerçek merchant ayarları, gerçek payment intent ve gerçek finansal sonuçlar ile çalışan ortamdır. |
| Terim | Tanım |
|---|
| Idempotency | Aynı request tekrar geldiğinde aynı iş sonucunun güvenli şekilde korunması yaklaşımıdır. Confirm, webhook ve retry akışlarında kritiktir. |
| Trace ID | Bir request veya payment attempt'i uçtan uca takip etmeye yarayan operasyonel kimliktir. |
| Credential Boundary | Provider credential ve hassas ayarların public dokümana, loglara veya sandbox test payload'larına taşınmaması gereken güvenlik sınırıdır. |
| Masking | Card data, CVV, credential, signature material ve raw provider secret gibi hassas alanların loglarda gizlenmesidir. |
| Secure Mode | 3DS veya ek authentication/authorization davranışı gerektirebilecek ödeme modudur. |
| Requires Action | Payment'ın devam etmek için kullanıcı aksiyonu, redirect, challenge veya resume beklediğini gösteren normalized result'tır. |
| Terim | Tanım |
|---|
| Event | Payment, charge, refund veya sistem state değişikliğini temsil eden domain sinyalidir. |
| Webhook | Event'in merchant backend'e HTTP üzerinden iletilmesidir. |
| Webhook Delivery | Event'in merchant endpoint'ine gönderilmesi, retry edilmesi ve teslim durumunun izlenmesidir. |
| Duplicate Delivery | Aynı webhook event'inin birden fazla kez ulaşabilmesidir. Merchant handler idempotent olmalıdır. |
| Reconciliation | Payment, charge, provider reference ve merchant order state'lerinin mutabakat sürecidir. |
| Terim | Tanım |
|---|
| Merchant Operations | Payment state, provider attempt, webhook delivery, refund/capture/void ve incident takibinin operasyonel yönetimidir. |
| Provider Health | Provider'ın degraded, unavailable veya timeout gibi operasyonel durum sinyalidir. Sandbox'ta simulated olabilir. |
| Decline Type | Decline sonucunun hard veya soft olarak ayrılmasıdır. Hard decline retry edilmez; soft decline uygun ise fallback/retry alabilir. |
| Pre-production Readiness | Production'a çıkmadan önce sandbox, webhook, credential, trace, decline ve 3DS davranışlarının doğrulanmasıdır. |
- Payment ve Charge aynı şey değildir.
- Payment Method ve Provider aynı şey değildir.
- Sandbox gerçek finansal ağ değildir.
- Return URL webhook yerine geçmez.
- Provider raw response public normalized modelin yerine geçmez.
- Provider ekleme JSON/YAML dosyası yazmak gibi anlatılmamalıdır; public dokümanda güvenli model provider catalog, config, adapter,
routing_strategy ve confirm orchestrator kavramlarıdır.
- "Strategy Execution" ürün adımı kodda yoktur; dokümanlarda provider adapter execution veya confirm orchestrator kullanın.