Ödeme Akışları

HSRC Pay'de create, confirm, requires_action, success, decline, capture, refund, cancel ve webhook akışlarının üst seviye haritası.

Bu sayfa HSRC Pay ödeme akışlarının üst seviye haritasını verir. Payment lifecycle'a giriş yapmak, Hosted Checkout ile API-only entegrasyon farkını görmek ve alt sayfalara doğru sırayla ilerlemek için okunmalıdır.

Ödeme entegrasyonu sadece endpoint çağırmak değildir; state, provider davranışı, risk, routing ve event disiplinidir.

Ödeme akışı nedir?

HSRC Pay'de ödeme akışı merchant'ın Payment oluşturmasıyla başlar (CREATED), Confirm ile provider execution sürecine girer ve adapter sonucu ile Payment/Charge state'lerine yansır.

Temel model:

Payment oluşturulur (POST /v1/payments).
Payment Method seçilir veya Checkout Session içinde toplanır.
Confirm çağrısı execution'ı başlatır (POST /v1/payments/:id/confirm).
Routing planı provider candidate'larını sıralar.
Her aday için Charge oluşturulur ve provider adapter pay çalışır.
Adapter sonucu success, requires_action veya error (içinde declined) olarak döner.
Payment status ve Charge status güncellenir.
Event/webhook merchant sistemine gönderilir.

Temel akış: create -> confirm -> result

Aşama	Sorumluluk	Not
Create	Payment niyetini hazırlar	`status: CREATED`, para çekmez
Confirm	Provider execution sürecini başlatır	Yanıt: `data.payment` + `data.confirmResult`
Result	Adapter + Payment/Charge status	`confirmResult.latestResult.kind` ile `payment.status` birlikte okunur
Event/Webhook	State değişimini backend'e taşır	Nihai doğrulama için kritiktir

const { data: created } = await api.post("/v1/payments", {
  amount: 12500,
  currency: "TRY",
  auto_capture: true,
});

const { data } = await api.post(`/v1/payments/${created.payment.id}/confirm`, {
  payment_method: { id: "pm_123" },
  payer_identity: { ip_address: clientIp, user_agent: ua },
});

if (data.payment.status === "REQUIRES_ACTION" && data.confirmResult.paymentNextAction?.url) {
  redirectUser(data.confirmResult.paymentNextAction.url);
}

Hosted Checkout akışı

Hosted Checkout, ödeme deneyimini Checkout Session içinde yönetir.

Bu modelde merchant:

Checkout Session oluşturur.
Kullanıcıyı checkout URL/token ile yönlendirir.
Payment Method toplama ve bazı 3DS/REQUIRES_ACTION adımlarını checkout deneyimine bırakır.
Nihai sonucu webhook veya GET /v1/payments/:id ile doğrular.

Hosted Checkout hızlı entegrasyon ve daha kontrollü ödeme deneyimi için önerilir.

API-only akış

API-only modelde merchant kendi frontend ve backend deneyimini yönetir.

Bu modelde merchant:

Payment Method toplama UI'ını yönetir.
Confirm çağrısını doğrudan yapar.
REQUIRES_ACTION ve paymentNextAction gelirse yönlendirme/challenge adımını yönetir.
Gateway 3DS callback sonrası webhook veya payment sorgusu ile nihai state'i doğrular.

API-only akış özel checkout, platform deneyimi veya daha fazla UI kontrolü isteyen ekipler için uygundur.

3DS / requires_action akışı

Her ödeme direkt SUCCEEDED veya AUTHORIZED dönmez. secure_mode veya provider gereksinimi nedeniyle adapter requires_action dönebilir; Payment REQUIRES_ACTION olur.

Bu durumda:

Confirm sonucu confirmResult.ok === true ve payment.status === "REQUIRES_ACTION" olabilir.
Merchant confirmResult.paymentNextAction.url ile kullanıcıyı yönlendirir.
Challenge sonrası gateway three-d-secure-callback-urls/:id üzerinden resume işler.
Final state event/webhook veya payment GET ile doğrulanır.

Async ve belirsiz sonuç

Bazı provider davranışları anlık terminal sonuç üretmeyebilir. Timeout veya belirsiz durumda merchant yeni Payment açmak yerine mevcut Payment'ı (include_charges=true) idempotent şekilde sorgulamalıdır.

Payment'ta ayrı PENDING adapter kind'ı yoktur; async bekleme genelde PROCESSING status veya operasyonel izleme ile yönetilir.

Webhook/event akışı

Frontend veya confirm response kullanıcı deneyimini yönlendirir; webhook merchant backend state'ini kapatır.

Webhook handler:

Idempotent olmalı
Duplicate delivery'yi tolere etmeli
Payment ID ve trace/request id ile kayıt eşleştirmeli
payment.succeeded, payment.requires_action, payment.authorized, charge.declined gibi event tiplerini ayrı yorumlamalı

Capture / refund / cancel

Operasyon	Koşul	Etki
Capture	Payment `AUTHORIZED`, `auto_capture: false`	Charge capture, Payment `SUCCEEDED`
Refund	Başarılı tahsilat sonrası	Refund kaydı, Payment `REFUNDED`
Cancel	Payment `AUTHORIZED`	Authorization iptali, Payment `CANCELED`

Bu operasyonlar Payment bağlamında görünür; finansal etki Charge seviyesinde izlenir.

Hata / decline davranışları

Başarılı ödeme entegrasyonu sadece success response ile değil, decline, timeout, 3DS ve webhook davranışını doğru yönetmekle anlaşılır.

Decline: Charge DECLINED, Payment çoğunlukla REQUIRES_PAYMENT_METHOD (yeniden confirm planlanabilir).
Hard decline: Aynı kartla agresif retry yapmayın; farklı yöntem veya kullanıcı aksiyonu isteyin.
Soft decline: Routing bir sonraki provider adayını deneyebilir (yeni charge attempt).
Timeout: Yeni payment açmadan önce GET /payments/:id ve webhook loglarını kontrol edin.
3DS failed: REQUIRES_ACTION veya REQUIRES_PAYMENT_METHOD sonrası kontrollü yeniden deneme.

İlgili sayfalar

Confirm detayı için Ödeme Yaşam Döngüsü ve Confirm
Hosted checkout için Checkout Session Rehberi
Payment/Charge domain ayrımı için Business Flow - Payments & Charges
Decline testleri için Testing Declines
3DS flow için 3DS Simulation

Ödeme Akışları

Bu sayfada