API Referansına Dön ÖdemelerÖdeme Oturumu Oluştur

Ödeme Oturumu Oluştur

POST/v1/payments/sessionsCore

Barındırılan bir ödeme sayfası oturumu oluşturur. Oturum; tutarı, açıklamayı ve yönlendirme URL'lerini taşır, alıcı kart (veya TR QR) akışını Kvell'in barındırdığı sayfa üzerinden tamamlar. Kart ile ödeme yerine BKM/TCMB TR QR ödemesi oluşturmak için mode="qr" değerini ayarlayın.

Kimlik Doğrulama

İmza Deseni

HMAC-SHA256(secretKey, "{timestamp}\nPOST\n/v1/payments/sessions\n{sha256(body)}")

Başlık	Değer	Açıklama
`X-Api-Key`	pk_live_a1b2c3d4e5f6g7h8	Merchant public API key
`X-Signature`	{hmac_sha256_hex}	Hex HMAC-SHA256 request signature (see below)
`X-Timestamp`	2026-04-13T10:00:00Z	ISO 8601 UTC request time, validated within ±5 min

İstek Parametreleri

Ad	Tür	Zorunlu	Açıklama
`transactionId`	string	Zorunlu	Unique merchant transaction id (idempotency fence, unique per merchant)
`amount`	integer	İsteğe Bağlı	Amount in kuruş (1/100 TRY). >=100 for mode="payment"/"qr"; omit for mode="card_update_only"
`currency`	string	Zorunlu	ISO 4217, always "TRY" in Phase 1
`description`	string	İsteğe Bağlı	Transaction description shown on the checkout page
`returnUrl`	string	Zorunlu	Redirect URL after the buyer finishes (success or failure)
`callbackUrl`	string	İsteğe Bağlı	Override the store default webhook URL for this payment
`installmentEnabled`	boolean	İsteğe Bağlı	Show the installment picker on the hosted page
`customerId`	string	İsteğe Bağlı	Bind the session to a saved customer (enables save-card)
`mode`	string	İsteğe Bağlı	"payment" (default) \| "card_update_only" \| "qr"
`splits`	array	İsteğe Bağlı	Marketplace split config [{submerchantId, amountMinor}] — payment mode only

İstek Örneği

JSONİstek Gövdesi

{
  "transactionId": "ORDER-2026-001",
  "amount": 15000,
  "currency": "TRY",
  "description": "Order #1234",
  "returnUrl": "https://merchant.example.com/return"
}

Yanıt Parametreleri

Alan	Tür	Örnek
`sessionId`	string	"3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f"
`checkoutUrl`	string	"https://pay.kvell.group/s/3f1c9a2e-6b4d-…
`expiresAt`	string	"2026-04-13T10:30:00Z"
`merchantId`	string	"mrc_8a1b2c3d4e5f"
`amount`	integer	15000
`currency`	string	"TRY"
`status`	string	"active"

Yanıt Örneği

JSONYanıt

{
  "sessionId": "3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "checkoutUrl": "https://pay.kvell.group/s/3f1c9a2e-6b4d-4e8a-9c1f-2a7b8c9d0e1f",
  "expiresAt": "2026-04-13T10:30:00Z",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "amount": 15000,
  "currency": "TRY",
  "status": "active"
}

Durum Kodları

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

DeneSahte

POSThttps://api.pay.sandbox.kvell.group

Tokenize Karttan Çekim Yap→