Checkout Session Rehberi

Bu sayfa Checkout Session'ın ne olduğunu, ne zaman kullanılacağını ve Hosted Checkout ile API-only payment flow arasındaki farkları açıklar.

Checkout Session, HSRC Pay'in hosted veya semi-hosted ödeme deneyimini yöneten oturum katmanıdır. Kullanıcıdan payment method ve checkout bağlamı toplanır; Confirm ile provider execution süreci başlatılır.

Checkout Session nedir?

Checkout Session, merchant'ın ödeme deneyimini hızlı ve kontrollü şekilde başlatması için oluşturduğu ödeme oturumudur. Session; amount, currency, customer bağlamı, redirect URL'leri, expiry, payment method seçimi ve final payment state ilişkisini taşır.

Bu model özellikle frontend ödeme formunu sıfırdan yönetmek istemeyen veya 3DS/redirect gibi multi-step flow'ları daha güvenli bir hosted deneyimde ele almak isteyen merchantlar için uygundur.

Ne zaman kullanılmalı?

• Hızlı entegrasyon istiyorsanız
• Hosted ödeme formu tercih ediyorsanız
• 3DS/requires_action handling'i checkout deneyimine bırakmak istiyorsanız
• Frontend'de card data exposure alanını azaltmak istiyorsanız
• Redirect, cancel ve return URL davranışını standartlaştırmak istiyorsanız

API-only flow ile farkı

Session lifecycle

Checkout Session status değerleri: PENDING, PROCESSING, COMPLETED, EXPIRED, CANCELLED, FAILED.

1. Merchant POST /v1/checkout-sessions ile oturum oluşturur (PENDING, token üretilir).
2. Payer, merchant'ın verdiği url (hosted sayfa) veya GET /v1/checkout-sessions/token/:token ile oturuma girer.
3. Checkout UI payment method ve payer alanlarını toplar; bağlı Payment CREATED olur.
4. Confirm ile provider execution başlar; Payment SUCCEEDED / AUTHORIZED / REQUIRES_ACTION / REQUIRES_PAYMENT_METHOD olabilir.
5. Session PROCESSING üzerinden terminal state'e (COMPLETED, FAILED, CANCELLED, EXPIRED) geçer.
6. Merchant webhook veya GET /v1/payments/:id ile nihai sonucu doğrular.

Kullanıcı deneyimi

Checkout confirm tarafında şu alanlar toplanabilir:

• Payer adı, e-posta ve telefon
• Fatura adresi
• Teslimat adresi
• shipping_same_as_billing gibi sadeleştirme sinyalleri
• Merchant tarafından tanımlanan custom fields

Bu alanlar payment execution başlamadan önce oturum bağlamında tamamlanır.

3DS / requires_action yönetimi

Secure mode açık olduğunda veya issuer/provider behavior challenge gerektirdiğinde Payment REQUIRES_ACTION olur; confirmResult.paymentNextAction (redirect_user_to_url) checkout içinde yönlendirme sağlar.

API-only modelde merchant frontend aynı sorumluluğu paymentNextAction ile taşır.

Redirect ve return URL davranışı

Return URL kullanıcı deneyimini kapatmak içindir; nihai finansal kanıt değildir. Kullanıcı browser'ı kapatabilir, redirect gecikebilir veya provider async sonuç üretebilir.

Webhook ile sonucu doğrulama

Merchant backend ödeme sonucunu webhook ile kapatmalıdır. Webhook handler:

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

Güvenlik notları

• Production card data ve credential'ları sandbox ortamına taşımayın.
• Raw card data, CVV, challenge HTML veya provider secret loglamayın.
• Checkout token'larını kısa ömürlü ve bağlama özel ele alın.
• Return/cancel URL'leri açık redirect risklerine karşı doğrulayın.

Örnek entegrasyon akışı

const { data } = await api.post("/v1/checkout-sessions", {
  amount: 12500,
  currency: "TRY",
  url: "https://pay.merchant.example/checkout",
  return_url: "https://merchant.example/return",
  metadata: { order_id: "ord_123" },
});

// Payer: merchant hosted sayfa veya token ile oturum
redirectUserTo(`${data.checkout_session.url}?token=${data.checkout_session.token}`);

// Webhook tarafı
if (event.type === "payment.succeeded") {
  await markOrderPaid(event.paymentId);
}

Best practices

• Hosted checkout kullanırken de backend doğrulamasını ihmal etmeyin.
• Session expiry ve cancel davranışına kullanıcı dostu dönüş yolu sunun.
• requires_action sonucunu normal flow parçası kabul edin.
• Session ile Payment ilişkisini operasyon ekranlarında izlenebilir tutun.
• Sandbox'ta success, decline, timeout ve 3DS senaryolarını test edin.

Related docs

• Ödeme Yaşam Döngüsü ve Confirm
• 3DS Simulation
• Sandbox Cards
• Webhook Delivery
• Testing Declines