Pazaryeri ve Bölünmüş Ödemeler

Kvell'in pazaryeri akışı, tek bir ödemenin birden fazla alıcı arasında bölüştürülmesini sağlar — birden çok satıcı adına satış yapan bir platform kendi payını tutar ve kalan tutarı, parayı hiç eline almadan doğrudan her satıcının kendi tahsilat bakiyesine yönlendirir. Bölüştürme, alt üye işyeri (submerchant) onboarding süreci ve ödemeler (payout) bu akışın üç temel parçasıdır; bu rehberde her üçünü de eksiksiz bir örnekle birlikte ele alıyoruz.

Bölüştürme nasıl çalışır#

• splits dizisiyle oluşturulan bir ödeme oturumu bir bölünmüş ödemedir. Her giriş bir submerchantId ile o alt üye işyerinin payını (amountMinor) belirtir; bölüştürülen tutarlar toplandıktan sonra kalan miktar platformda (üst üye işyerinde) kalır.
• Her bölüştürme alıcısı bir **alt üye işyeri (submerchant)**dir — platform üye işyeri hesabınız altında kendi kimliği, KYC durumu ve tahsilat bakiyesi olan bir satıcı. Bir alt üye işyeri ancak KYC durumu aktif olduğunda ödeme alabilir; splits içinde onaylanmamış bir alt üye işyeri listelenirse oturum oluşturma çağrısı başarısız olur.
• splits[].amountMinor toplamı, oturumun amount alanını aşamaz. Kvell bölüştürmeyi asla kendiliğinden çıkarsamaz — bir satıcıyı listeye eklemezseniz, o ödemeden hiçbir pay almaz.
• Normal bir ödemede zaten kullandığınız her şey — 3DS, taksit, tahsilat (capture), iade — bu akışın altında değişmeden çalışır. Bölüştürme yalnızca elde edilen tutarın dahili olarak nasıl dağıtıldığını değiştirir. Bu akışı henüz kurmadıysanız Kart Ödemelerini Kabul Etme rehberine bakın.

Bir alt üye işyerini sisteme dahil etme#

Alt üye işyeri oluşturma, kimlik bilgisi toplama ve KYC incelemesi üye işyeri panosu (dashboard) üzerinden yapılır — bunun için imzalı genel API'de bir çağrı yoktur. Bir alt üye işyeri KYC sürecini tamamlayıp aktif hale geldiğinde, entegrasyonunuzda iki şekilde yer alır:

• bölüştürme alıcısı olarak — bir ödeme oturumunda splits içine submerchantId değerini geçirin
• ödeme (payout) alıcısı olarak — submerchantId değerini POST /v1/payouts çağrısına geçirin

Her alt üye işyerine ayrıca yalnızca kendisi için geçerli, dar kapsamlı kendi API anahtarı verilir. Bir anahtarın hangi tür çağırana ait olduğunu doğrulamak için:

curl https://api.pay.kvell.group/v1/auth/whoami \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>"

{
  "subjectScope": "merchant",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "apiKeyId": "key_708192a3b4c5"
}

subjectScope, platform anahtarınız için "merchant", bir satıcının kendi anahtarı için "submerchant" değerini alır. Bir alt üye işyerinin KYC kararını da kendi kararınızı okuduğunuz şekilde okursunuz — Canlıya Geçiş rehberinde ele alınan GET /v1/kyc/status.

Örnek senaryo: iki satıcı arasında bölüştürülen 1.200 TRY'lik bir sipariş#

Bir pazaryeri platformu, iki farklı satıcının ürünlerinden oluşan 1.200,00 TRY'lik (120000 kuruş) bir sipariş satar. A satıcısının payı 700,00 TRY, B satıcısının payı 400,00 TRY'dir; platform kalan 100,00 TRY'yi kendi komisyonu olarak tutar.

1. Bölünmüş ödeme oturumunu oluşturun#

curl -X POST https://api.pay.kvell.group/v1/payments/sessions \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "ORDER-2026-4521",
    "amount": 120000,
    "currency": "TRY",
    "description": "Sipariş #4521 (2 satıcı)",
    "returnUrl": "https://marketplace.example.com/return",
    "splits": [
      { "submerchantId": "sub_7f3a9c21", "amountMinor": 70000 },
      { "submerchantId": "sub_2b88e04d", "amountMinor": 40000 }
    ]
  }'

{
  "sessionId": "4d4e8a9c-1f2a-7b8c-9d0e-1f3f1c9a2e6b",
  "checkoutUrl": "https://pay.kvell.group/s/4d4e8a9c-1f2a-7b8c-9d0e-1f3f1c9a2e6b",
  "expiresAt": "2026-04-13T10:30:00Z",
  "amount": 120000,
  "currency": "TRY",
  "status": "active"
}

Alıcıyı checkoutUrl adresine yönlendirin. Sonrasındaki her şey — 3DS, taksit, tahsilat — normal bir hosted checkout akışıyla birebir aynı şekilde işler.

2. Tahsilat webhook'unu alın#

Alıcı ödemeyi tamamladığında, Kvell herhangi bir kart tahsilatında alacağınız aynı payment.captured olayını gönderir:

X-Kvell-Event: payment.captured
X-Kvell-Event-Id: evt_5b6c7d8e9f0a
X-Kvell-Delivery: whd_0f1a2b3c4d5e
X-Kvell-Signature: sha256=8f0e1d2c3b4a59687a1e2d3c4b5a6978c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f
X-Request-Id: 3c9e6a1b-7f2d-4e8a-b1c9-0d2f3a4b5c6d

{
  "eventId": "evt_5b6c7d8e9f0a",
  "eventType": "payment.captured",
  "occurredAt": "2026-04-13T10:00:05Z",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "payload": {
    "paymentId": "pay_1a2b3c4d5e6f",
    "transactionId": "ORDER-2026-4521",
    "amount": 120000,
    "currency": "TRY",
    "status": "captured"
  }
}

Olay, satıcı bazında bir dağılım değil, sipariş toplamını taşır — Kvell her satıcının payını dahili olarak takip eder. Bölüştürmeyi alıcıya göstermeniz veya kendi sipariş kayıtlarınızla eşleştirmeniz gerekiyorsa GET /v1/payments/{id} çağrısını kullanın.

3. Her satıcıya ödeme yapın#

Bir satıcının payı hesaba yattıktan sonra, bunu bir alt üye işyeri ödemesiyle (submerchant payout) satıcıya aktarın. Hedef IBAN ve hesap sahibi bilgisi alt üye işyerinin kendi kaydından alınır — siz yalnızca tutarı belirtirsiniz:

curl -X POST https://api.pay.kvell.group/v1/payouts \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:05:00Z" \
  -H "X-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "submerchantId": "sub_7f3a9c21",
    "rail": "fast",
    "amountMinor": 70000,
    "currency": "TRY"
  }'

{
  "payoutId": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "status": "pending",
  "submerchantId": "sub_7f3a9c21"
}

B satıcısı için aynı işlemi amountMinor: 40000 ile tekrarlayın. Her ödeme asenkron olarak sonuçlanır — GET /v1/payouts/{id} ile durumu sorgulayın veya webhook uç noktanızda payout.succeeded / payout.failed olaylarını dinleyin. Canlıya geçmeden önce her iki sonucu da denemek için Sandbox Ortamında Test Etme rehberindeki payout-success / payout-declined senaryolarına bakın.

Alt üye işyeri ödemeleri için kullanılabilecek yöntemler#

rail alanı normal bir ödemedeki aynı üç değeri kabul eder:

Bölünmüş bir ödemede iade#

Bölünmüş bir ödemeyi, herhangi bir ödemeyi iade ettiğiniz şekilde iade edin — POST /v1/payments/{id}/refund. Kvell, iade edilen tutarı orijinal alıcılar (platform ve her alt üye işyeri) arasında orantılı olarak geri alır; böylece kimsenin payı aldığı miktarla orantısız şekilde iade edilmez. Yukarıdaki örnek üzerinde yapılacak kısmi bir iade, her tarafın tutulan bakiyesini orijinal tahsilatın kendisine kazandırdığı oranla azaltır.

Ödeme yapmadan önce kullanılabilir bakiyeyi kontrol etme#

Ödeme göndermeden önce, gerçekte ne kadar bekleyen tutar olduğunu doğrulayın:

curl https://api.pay.kvell.group/v1/payouts/outstanding \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>"

{
  "merchantId": "mrc_8a1b2c3d4e5f",
  "pendingMinor": 250000,
  "currency": "TRY"
}

Çok sayıda satıcı için, POST /v1/payouts çağrısını bir döngü içinde tekrarlamak yerine ödemeleri toplu olarak gönderin — aşağıdaki Çok sayıda satıcı için toplu ödeme bölümüne bakın.

Çok sayıda satıcı için toplu ödeme#

Aynı seferde onlarca alt üye işyerine ödeme yapıyorsanız — örneğin haftalık bir satıcı hakediş ödemesi — ödemeleri teker teker göndermek yerine bir taslak (draft) yükleyin:

curl -X POST https://api.pay.kvell.group/v1/payout-drafts \
  -H "X-Api-Key: pk_live_a1b2c3d4e5f6g7h8" \
  -H "X-Timestamp: 2026-04-13T10:00:00Z" \
  -H "X-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "sto_5a6b7c8d",
    "rows": [
      { "rail": "fast", "dest": "TR330006100519786457841326", "holderName": "Satıcı A", "amountMinor": 70000, "currency": "TRY" },
      { "rail": "fast", "dest": "TR120006200119000006672315", "holderName": "Satıcı B", "amountMinor": 40000, "currency": "TRY" }
    ]
  }'

{
  "draftId": "drf_8192a3b4c5d6",
  "status": "draft",
  "rowCount": 2,
  "validCount": 2,
  "invalidCount": 0,
  "createdAt": "2026-04-13T10:00:00Z"
}

Taslağı GET /v1/payout-drafts/{id} ile inceleyin, ardından POST /v1/payout-drafts/{id}/approve çağrısını yapın — Kvell, satır başına en fazla bir kez olmak üzere her doğrulanmış satırı gerçek bir ödemeye dönüştürür. Bir taslak en fazla 1.000 satır kabul eder, tek bir taslakta yalnızca bir mağaza (store) olabilir ve dest alanı (IBAN veya kart token'ı) hiçbir yanıtta geri döndürülmez.

Pazaryeri ödemelerine özgü hatalar#

Sonraki adımlar#