vellTRDocs
API Referansına Dön

Ödemeler

Kart ödemeleri ve TR Karekod kabul edin. Ödeme oturumları oluşturun, tokenize kartlardan çekim yapın (3DS 2.0), ön provizyon/çekim/iptal ve iade işlemleri yürütün.

8 endpoints
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.

İstek Parametreleri

AdTürZorunluAçıklama
transactionIdstringZorunluUnique merchant transaction id (idempotency fence, unique per merchant)
amountintegerİsteğe BağlıAmount in kuruş (1/100 TRY). >=100 for mode="payment"/"qr"; omit for mode="card_update_only"
currencystringZorunluISO 4217, always "TRY" in Phase 1
descriptionstringİsteğe BağlıTransaction description shown on the checkout page
returnUrlstringZorunluRedirect URL after the buyer finishes (success or failure)
callbackUrlstringİsteğe BağlıOverride the store default webhook URL for this payment
installmentEnabledbooleanİsteğe BağlıShow the installment picker on the hosted page
customerIdstringİsteğe BağlıBind the session to a saved customer (enables save-card)
modestringİsteğe Bağlı"payment" (default) | "card_update_only" | "qr"
splitsarrayİsteğe BağlıMarketplace split config [{submerchantId, amountMinor}] — payment mode only
JSONİstek Örneği
{
  "transactionId": "ORDER-2026-001",
  "amount": 15000,
  "currency": "TRY",
  "description": "Order #1234",
  "returnUrl": "https://merchant.example.com/return"
}
JSONYanıt Örneği
{
  "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"
}
POST/v1/payments/cardCore

Bir vault token kullanarak karttan çekim yapar (asla ham PAN ile değil — önce POST /v1/cards/tokens ile tokenize edin). 3DS 2.0 doğrulama sürecini yönetir. Ön provizyon için (Slice 9) capture=false ayarlayın: kayıt, sonraki bir /capture veya /void çağrısına kadar hiçbir defter kaydı oluşturulmadan status="authorized" durumunda kalır.

İstek Parametreleri

AdTürZorunluAçıklama
transactionIdstringZorunluSession transaction id (idempotency fence)
amountintegerZorunluAmount in kuruş
currencystringZorunluAlways "TRY"
cardTokenstringZorunluVault token (tok_…) from POST /v1/cards/tokens
installmentCountintegerİsteğe BağlıInstallment count 1..12 (re-checked against installment-service)
threeDSecurebooleanİsteğe BağlıForce 3DS (default true)
customerIdstringİsteğe BağlıSave-card is honored only for a session-bound customer
saveCardbooleanİsteğe BağlıAttach the card to the customer after capture
capturebooleanİsteğe BağlıAuto-capture (default true); false = preauth
JSONİstek Örneği
{
  "transactionId": "ORDER-2026-001",
  "amount": 15000,
  "currency": "TRY",
  "cardToken": "tok_9f8e7d6c5b4a",
  "installmentCount": 3
}
JSONYanıt Örneği
{
  "paymentId": "pay_1a2b3c4d5e6f",
  "status": "captured",
  "amount": 15000,
  "currency": "TRY",
  "commission": 449,
  "netAmount": 14551,
  "cardMask": "415565******4321",
  "cardBrand": "visa",
  "cardType": "credit",
  "installmentCount": 3,
  "threeDSecure": true,
  "authCode": "123456",
  "createdAt": "2026-04-13T10:00:00Z",
  "completedAt": "2026-04-13T10:00:02Z"
}
POST/v1/payments/{id}/3ds-callbackOptional

Bir 3DS doğrulama sürecini tamamlar. Barındırılan ödeme sayfası, ACS pares değerini ve kart çekim yanıtından dönen correlationId'yi gönderir. Idempotent'tir — tekrarlanan bir gönderim, kazanan kaydı bayt bayt aynı şekilde döndürür.

İstek Parametreleri

AdTürZorunluAçıklama
paresstringZorunluSigned ACS assertion from the 3DS challenge
correlationIdstringZorunluValue round-tripped from the card charge response
JSONİstek Örneği
{
  "pares": "eyJjaGFsbGVuZ2VJZCI6Ii4uLiJ9.9a8b7c6d",
  "correlationId": "c0rr-3f1c-9a2e-6b4d"
}
JSONYanıt Örneği
{
  "id": "pay_1a2b3c4d5e6f",
  "status": "captured",
  "amount": 15000,
  "currency": "TRY",
  "commission": 449,
  "netAmount": 14551,
  "authCode": "123456",
  "completedAt": "2026-04-13T10:00:05Z"
}
POST/v1/payments/{id}/captureRecommended

Ön provizyonu alınmış bir ödemeyi çeker (yalnızca tam tutar — kısmi/çoklu çekim Faz 2 kapsamındadır). Zaten çekilmiş bir kayıt için idempotent'tir.

JSONİstek Örneği
{}
JSONYanıt Örneği
{
  "id": "pay_1a2b3c4d5e6f",
  "status": "captured",
  "amount": 15000,
  "currency": "TRY",
  "commission": 449,
  "netAmount": 14551,
  "refundableAmount": 15000,
  "completedAt": "2026-04-13T10:05:00Z"
}
POST/v1/payments/{id}/voidRecommended

Çekilmemiş bir provizyonu serbest bırakır. Hiçbir defter kaydı oluşturulmaz (Kvell'in kayıtlarında para hareketi olmaz). Zaten iptal edilmiş bir kayıt için idempotent'tir.

İstek Parametreleri

AdTürZorunluAçıklama
reasonstringİsteğe BağlıFree text (≤500 chars), surfaced on the payment.voided event
JSONİstek Örneği
{
  "reason": "Order abandoned"
}
JSONYanıt Örneği
{
  "id": "pay_1a2b3c4d5e6f",
  "status": "voided",
  "amount": 15000,
  "currency": "TRY"
}
POST/v1/payments/{id}/refundCore

Çekilmiş bir ödemeyi tamamen veya kısmen iade eder. İade senkron olarak tamamlandığında 200, işlem devam ederken (refund-reconciler tarafından tamamlanır — 202 durumunda yeni bir Idempotency-Key üretmeyin) 202 döner. İsteğe bağlı bir Idempotency-Key başlığını destekler.

İstek Parametreleri

AdTürZorunluAçıklama
amountintegerİsteğe BağlıPartial refund amount in kuruş (<= refundableAmount). Omit for a full refund.
reasonstringİsteğe BağlıRefund reason (truncated at 500 chars)
JSONİstek Örneği
{
  "amount": 5000,
  "reason": "Customer request"
}
JSONYanıt Örneği
{
  "paymentId": "pay_1a2b3c4d5e6f",
  "status": "captured",
  "refundAmount": 5000,
  "refundableAmount": 10000,
  "lastRefund": {
    "refundId": "rfn_7c8d9e0f1a2b",
    "status": "completed",
    "amount": 5000,
    "bankRefundId": "rfn_mock_44182",
    "createdAt": "2026-04-13T14:00:00Z",
    "completedAt": "2026-04-13T14:00:01Z"
  }
}
GET/v1/payments/{id}Core

Tam ödeme nesnesini getirir.

JSONYanıt Örneği
{
  "id": "pay_1a2b3c4d5e6f",
  "merchantId": "mrc_8a1b2c3d4e5f",
  "transactionId": "ORDER-2026-001",
  "status": "captured",
  "amount": 15000,
  "currency": "TRY",
  "commission": 449,
  "netAmount": 14551,
  "cardMask": "415565******4321",
  "cardBrand": "visa",
  "cardType": "credit",
  "bin": "415565",
  "installmentCount": 3,
  "threeDSecure": true,
  "refundAmount": 0,
  "refundableAmount": 15000,
  "createdAt": "2026-04-13T10:00:00Z",
  "completedAt": "2026-04-13T10:00:02Z"
}
GET/v1/payments/{id}/public-statusRecommended

Alıcı için güvenli durum sorgulama — kimlik doğrulama gerektirmez (paymentId UUID'si bearer görevi görür). QR alıcı sayfası ve kart akışındaki başarı sorgulaması tarafından kullanılır. Yalnızca dar bir alan kümesi döner (asla PAN, komisyon, üye işyeri kimliği veya yetkilendirme kodu içermez).

JSONYanıt Örneği
{
  "paymentId": "pay_1a2b3c4d5e6f",
  "status": "captured"
}

Kategori Özeti

Toplam Endpoint

8

Ana Domain

api.pay.kvell.group