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.

Ö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": "5406681122223338",
  "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

Alan	Tip	Açıklama
`orderNumber`	string	Sizin 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.
`idempotencyKey`	string	Sizin 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.
`paymentMethod`	enum	Ö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. `CARDSAVED_CARDPRE_AUTH_CARD`
`amount`	decimal	İş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.
`currency`	string	3 harfli ISO-4217 para birimi kodu (örn. TRY). Boş bırakılırsa TRY. Varsayılan: `TRY`
`customerId`	string	Müşteri kimliği (opsiyonel).
`savedCardId`	string	Kayıtlı kart kimliği. paymentMethod=SAVED_CARD için kullanılır.
`cardNumber`	string	Kart numarası. Plain kart ödemesi (paymentMethod=CARD) için.
`cardHolderName`	string	Kart üzerindeki ad-soyad.
`expMonth`	integer	Son kullanma ayı (1-12).
`expYear`	integer	Son kullanma yılı (örn. 2030).
`cvv`	string	Kart güvenlik kodu.
`threeDsEnabled`	boolean	3D Secure akışını etkinleştirir.
`installment`	integer	Taksit sayısı. Belirtilmezse tek çekim.
`saveCard`	boolean	Ödeme başarılıysa kart saklansın mı. Saklama ödeme sırasında yapılır. Varsayılan false.
`preAuth`	boolean	Provizyonlu işlem (ön otorizasyon). true ise tutar bloke edilir, tahsilat kesinleşmez; kapatma ayrı çağrıyla yapılır. Varsayılan false.
`items`	array	Sepet 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[].name`	string	Kalem adı. Zorunlu.
`items[].unitPrice`	decimal	Birim fiyat. 0'dan büyük olmalıdır.
`items[].quantity`	integer	Adet. Gönderilmezse 1 kabul edilir.
`items[].vat`	decimal	KDV oranı. Negatif olamaz.
`items[].productCode`	string	Kendi ürün kodunuz (opsiyonel).
`items[].productId`	string	Kendi ürün kimliğiniz (opsiyonel).
`items[].variantId`	string	Kendi varyant kimliğiniz (opsiyonel).

Yanıt

Alan	Anlamı
`transactionRef`	Saklanacak tek değer. detail / capture / cancel / refund hepsi bunu alır. İşlem başarısız bitse de dolar.
`orderNumber`	Gönderdiğiniz sipariş numarasının yankısı; `transaction/search` ile filtrelenir.
`status`	Ödemenin sonucu — aşağıdaki tabloya bakın.
`requires3ds`	Müşteri yönlendirilecek mi. `true` ise `redirectUrl` ya da `htmlContent` doludur.
`redirectUrl` / `htmlContent`	Müşterinin yönlendirileceği adres ya da gömülecek 3DS formu.
`capturedDate`	Tahsilatı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_3DS`	Banka doğrulaması gerekiyor.	Müşteriyi `redirectUrl`'e yönlendirin; kesin sonucu transaction/detail ile sorgulayın.
`PRE_AUTHORIZED`	Provizyon açıldı, tutar bloke. Para hesabınıza geçmedi.	Tahsil etmek için transaction/capture çağırın.
`COMPLETED`	Tahsilat kapandı.	İşlem tamam.
`FAILED`	Ne 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, unitPrice ve pozitif quantity zorunludur; eksikse items.invalid döner.
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ı	HTTP	Neden
`items.total.mismatch`	406	Sepet kalemlerinin toplamı gönderilen amount ile eşleşmiyor.
`items.limit.exceeded`	400	Tek istekte izin verilen kalem sayısı (250) aşıldı.
`items.invalid`	400	Kalemde name, unitPrice veya pozitif quantity eksik.
`invalid.payment.method`	400	Geçersiz paymentMethod gönderildi. Boş bırakırsanız sunucu CARD / SAVED_CARD olarak türetir.
`pos.non.secure.not.allowed`	406	Bu POS 3D'siz işleme kapalı — threeDsEnabled: true gönderin.
`partner.api.amount.limit.exceeded`	406	Tutar, API anahtarınızın üst sınırını aşıyor.

İsteği Dene

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

Mock

orderNumberidempotencyKeypaymentMethodamountcurrencycustomerIdsavedCardIdcardNumbercardHolderNameexpMonthexpYearcvvthreeDsEnabledinstallmentsaveCardpreAuthitems (JSON)