Kart Ödemesi Al

POST/partner/1.0/pos/card/pay
Gerekli scope: payment:saleIdempotency-Key zorunlu

Kart veya kayıtlı kart ile manuel ödeme (POS) başlatır. Yanıttaki status alanını okumadan işlemi başarılı saymayın — 3DS yönlendirmesi, provizyon ve sağlayıcı reddi ayrı durumlardır.

Müşteriye ödemeden önce nihai tutarı göstermek istiyorsanız Komisyon Önizleme ucunu kullanın — aynı installment ile sorgulayın.

saveCard: true gönderirseniz kart, ödeme başarılı olduğunda saklanır ve sonraki ödemelerde savedCardId ile kullanılır (bkz. Kayıtlı Kart).

preAuth: true gönderirseniz tahsilat kesinleşmez: tutar karttan bloke edilir, tahsilat Provizyon Kapatma ile ayrı bir çağrıda yapılır.

İsteğe bağlı items ile sepet kalemi gönderebilirsiniz — aşağıdaki Sepet Kalemleri bölümüne bakın.

Bu uç işletmenizde manuel tahsilat (CHECKOUT_MANUAL) modülünün satın alınmış olmasını gerektirir.

Örnek

curl -X POST https://<host>/partner/1.0/pos/card/pay \
  -H "X-Api-Key: ..." \
  -H "X-Timestamp: ..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: card-pay-ORD-1001" \
  -H "Content-Type: application/json" \
  -d '{
  "orderNumber": "ORD-1001",
  "paymentMethod": "CARD",
  "amount": 100,
  "currency": "TRY",
  "cardNumber": "5127541122223332",
  "cardHolderName": "Test User",
  "expMonth": 12,
  "expYear": 2030,
  "cvv": "000",
  "threeDsEnabled": false,
  "installment": 1,
  "items": [
    {
      "name": "Kablosuz Kulaklık",
      "unitPrice": 40,
      "quantity": 2,
      "vat": 20,
      "productCode": "SKU-1"
    },
    {
      "name": "Kılıf",
      "unitPrice": 20,
      "quantity": 1,
      "vat": 20,
      "productCode": "SKU-2"
    }
  ]
}'

İstek Body

AlanTipAçıklama
orderNumberstringSizin kendi sipariş numaranız. İşlem kaydına yazılır ve transaction/search ile bu numaradan aranabilir. Tekil olmak zorunda değildir — kombine ödemede aynı sipariş birden fazla işlem satırı üretebilir.
idempotencyKeystringSizin kendi referansınız; yalnız işlem kaydına yazılır. Tekrar koruması bu alandan DEĞİL, zorunlu Idempotency-Key header'ından gelir.
paymentMethodenumÖdeme yöntemi. Boş bırakılırsa türetilir: savedCardId verilmişse SAVED_CARD, aksi hâlde CARD. PRE_AUTH_CARD gönderilirse CARD + preAuth: true olarak normalize edilir. Tanımsız bir değer boş kabul edilir ve aynı kuralla türetilir.
CARDSAVED_CARDPRE_AUTH_CARD
amountdecimalİşlem tutarı. items göndermezseniz zorunludur; sepet gönderirseniz boş bırakabilirsiniz — tutar kalem toplamından türetilir. Verirseniz kalem toplamıyla eşleşmelidir. 0'dan büyük, en fazla 2 ondalık basamaklı ve en fazla 999999.99 olmalıdır.
currencystring3 harfli ISO-4217 para birimi kodu (örn. TRY). Boş bırakılırsa TRY. Tanımsız bir kod currency.empty ile reddedilir.
Varsayılan: TRY
customerIdstringMüşteri kimliği (opsiyonel).
savedCardIdstringKayıtlı kart kimliği. paymentMethod=SAVED_CARD için kullanılır. Yalnız işletmeniz adına (customerId boş) saklanan kartlar kullanılabilir; müşteri adına saklanan kart storedbankcard.not.found döner.
cardNumberstringKart numarası. Plain kart ödemesi (paymentMethod=CARD) için. Boşluk/ayraç temizlenir ve Luhn ile doğrulanır.
cardHolderNamestringKart üzerindeki ad-soyad.
expMonthintegerSon kullanma ayı (1-12).
expYearintegerSon kullanma yılı (örn. 2030).
cvvstringKart güvenlik kodu.
threeDsEnabledboolean3D Secure akışı. Gönderilmezse 3D Secure uygulanır; 3D'siz ödeme için açıkça false gönderin.
Varsayılan: true
installmentintegerTaksit sayısı. Belirtilmezse tek çekim.
saveCardbooleanÖdeme başarılıysa kart saklansın mı. Saklama ödeme sırasında yapılır. Varsayılan false.
preAuthbooleanProvizyonlu işlem (ön otorizasyon). true ise tutar bloke edilir, tahsilat kesinleşmez; kapatma ayrı çağrıyla yapılır. Varsayılan false.
itemsarraySepet kalemleri (opsiyonel). amount ile birlikte gönderilirse kalem toplamı birebir eşleşmelidir; amount boşsa tutar kalemlerden türetilir. Tek istekte en fazla 250 kalem.
items[].namestringKalem adı. Zorunlu.
items[].unitPricedecimalBirim fiyat. 0'dan büyük olmalıdır.
items[].quantityintegerAdet. Gönderilmezse 1 kabul edilir; verilirse pozitif olmalıdır.
items[].vatdecimalKDV oranı (opsiyonel). Negatif olamaz. Yalnız oran kaydedilir; KDV tutarı hesaplanmaz.
items[].productCodestringKendi ürün kodunuz (opsiyonel). Kabul edilir ancak işlem kalemine kaydedilmez.
items[].productIdstringKendi ürün kimliğiniz (opsiyonel).
items[].variantIdstringKendi varyant kimliğiniz (opsiyonel).

Yanıt

AlanAnlamı
transactionRefSaklanacak tek değer. detail / capture / cancel / refund hepsi bunu alır. İşlem başarısız bitse de dolar.
orderNumberGönderdiğiniz sipariş numarasının yankısı; transaction/search ile filtrelenir.
statusÖdemenin sonucu — aşağıdaki tabloya bakın.
requires3dsMüşteri yönlendirilecek mi. true ise redirectUrl ya da htmlContent doludur.
redirectUrl / htmlContentMüşterinin yönlendirileceği adres ya da gömülecek 3DS formu.
capturedDateTahsilatın kapandığı an; kapanmadıysa null.
amount / currency / installmentİşlenen tutar, para birimi ve taksit sayısı.
Örnek yanıt (content)
{
  "orderNumber": "ORD-1001",
  "transactionRef": "eb334ec5-9f7a-4c21-9b3e-77a01c4f2d18",
  "status": "AWAITING_3DS",
  "amount": 100,
  "currency": "TRY",
  "installment": 1,
  "requires3ds": true,
  "redirectUrl": "https://<host>/3ds/eb334ec5-…",
  "htmlContent": null,
  "capturedDate": null
}

Yanıt Durumu

Yanıt zarfı (code: 200) yalnız isteğin işlendiğini söyler; ödemenin sonucu status alanındadır.

`status`AnlamıSıradaki adım
AWAITING_3DSBanka doğrulaması gerekiyor.Müşteriyi redirectUrl'e yönlendirin; kesin sonucu transaction/detail ile sorgulayın.
PRE_AUTHORIZEDProvizyon açıldı, tutar bloke. Para hesabınıza geçmedi.Tahsil etmek için transaction/capture çağırın.
COMPLETEDTahsilat kapandı.İşlem tamam.
FAILEDNe yönlendirme ne kapanış var — işlem gerçekleşmedi.Detay için transaction/detail.
PRE_AUTHORIZED tahsilat değildir

Provizyonu COMPLETED sanıp kapamayı çağırmazsanız bloke tutar banka süresi dolunca çözülür ve tahsilat hiç gerçekleşmez.

Sepet Kalemleri

items göndermek zorunlu değildir; göndermezseniz işlem tek satır olarak kaydedilir.

Gönderirseniz:

  • amount göndermezseniz tutar kalem toplamından (Σ unitPrice × quantity) türetilir.
  • amount de gönderirseniz kalem toplamıyla birebir eşleşmelidir. Eşleşmezse items.total.mismatch ile 406 döner; beklenen ve gönderilen tutar hata mesajında yer alır.
  • Tek istekte en fazla 250 kalem gönderilebilir (items.limit.exceeded).
  • name ve pozitif unitPrice zorunludur. quantity gönderilmezse 1 kabul edilir, verilirse pozitif olmalıdır; vat verilirse negatif olamaz. Aksi hâlde items.invalid döner.
  • productCode kabul edilir ama kaleme kaydedilmez; productId ve variantId kaydedilir.
  • Kalemler işlem kaydına ayrı satırlar olarak yazılır; her satırın kendi komisyon ve net tutarı hesaplanır.
  • İade ve iptal yine tutar bazlıdır; kalem bazlı iade yoktur.

Provizyon (Ön Otorizasyon)

preAuth: true ile başlatılan işlem karttan tutarı bloke eder, para hesabınıza geçmez. İşlem PRE_AUTHORIZED durumunda bekler.

Tipik kullanım: gerçekleşecek tutarın peşinen bilinmediği işler — otel, araç kiralama, kargo. Önce tahmini tutar bloke edilir, hizmet tamamlanınca gerçekleşen tutar çekilir.

  • Kapatma tutarı provizyondan küçük olabilir (kısmi kapatma); kalan bloke çözülür.
  • Kapatılmayan provizyon bankanın süresi dolunca kendiliğinden düşer — tahsilat gerçekleşmez.
  • Provizyon PRE_AUTHORIZED durumundadır; transaction/search ile {"status":"PRE_AUTHORIZED"} filtresiyle listelenir.
card/pay (preAuth: true)  →  PRE_AUTHORIZED  →  transaction/capture  →  COMPLETED
                                             ↘  transaction/cancel   →  bloke çözülür
Sağlayıcı desteği

Provizyon her sağlayıcıda yoktur. Desteklemeyen bir POS'a yönlenen istek reddedilir — sessizce normal tahsilata düşmez.

Hatalar

Mesaj anahtarıHTTPNeden
items.total.mismatch406Sepet kalemlerinin toplamı gönderilen amount ile eşleşmiyor.
items.limit.exceeded400Tek istekte izin verilen kalem sayısı (250) aşıldı.
items.invalid400Kalemde name, unitPrice veya pozitif quantity eksik.
amount.invalid400amount eksik, 0'dan büyük değil ya da 2'den fazla ondalık basamak içeriyor.
amount.exceeds.maximum400amount platform tavanını (999999.99) aşıyor.
currency.empty400currency tanımsız bir kod.
pos.card.number.must.be.valid400cardNumber Luhn doğrulamasından geçmedi.
idempotency.key.required400Idempotency-Key header'ı gönderilmedi.
pos.non.secure.not.allowed406Bu POS 3D'siz işleme kapalı — threeDsEnabled: true gönderin.
partner.api.amount.limit.exceeded406Tutar, API anahtarınızın üst sınırını aşıyor.
payment.not.completed406Ödeme sağlayıcı/handler seviyesinde tamamlanamadı.
storedbankcard.not.found404savedCardId bulunamadı ya da işletmeniz adına saklanmış bir kart değil.
stored.card.not.active406Kayıtlı kart ACTIVE değil (ör. REVOKED).
stored.card.not.allowed.for.pos406Kartın kullanım alanı POS_PAYMENT ya da BOTH değil.

İsteği Dene

İsteği Dene
Önizleme modu — değerler kod örneklerini günceller, gerçek istek atılmaz.
Mock