Alıcı Bilgileri

Ödemeyi yapan kişiyi iki ayrı alanla anlatırsınız:

• buyer: alıcının kişi bilgileri; ad, kimlik numarası, e-posta, telefon, IP adresi ve diğerleri. Ödeme kuruluşuna iletilir ve risk değerlendirmesinde kullanılır.
• customerId: alıcının sizin sisteminizdeki müşteri anahtarı. Ödemeleri müşteriye göre listelemenizi, kartları müşteri adına saklamanızı ve cüzdanla ödemede alıcının tanınmasını sağlar.

Alıcıyı alan uçlar

• Linkle Ödeme buyer ve customerId almaz. Alıcıdan hangi bilgilerin isteneceğini buyerFields ile seçer, bildiğiniz bilgileri prefill ile verirsiniz; bkz. Link Oluşturma.
• İsteğin üst seviyesinde ayrı bir e-posta ya da telefon alanı yoktur. Alıcının e-postasını buyer.email, telefonunu buyer.gsmNumber ile gönderin.

buyer alanları

buyer opsiyoneldir. Gönderirseniz aşağıdaki "Evet" alanlarının hepsi dolu olmalıdır. Checkout Formu intent'inde (POST /payments/intents, POST /payments/marketplace/intents) bu zorunluluk yoktur: alanların hepsi isteğe bağlıdır, gönderdiğiniz alanların tipi ve uzunluğu doğrulanır.

Zorunluluk kuralı

• buyer nesnesinin kendisi her uçta isteğe bağlıdır.
• POST /payments/direct/payment ile POST /payments/marketplace/2d ve /marketplace/3d uçlarında buyer gönderirseniz name, surname, identityNumber, email, gsmNumber, city, country, zipCode ve ip dolu metin olmalıdır. Boş metin de eksik sayılır.
• email, gönderildiği her uçta geçerli bir e-posta adresi olmalıdır.
• Checkout Formu intent'inde (POST /payments/intents, POST /payments/marketplace/intents) alanların hepsi isteğe bağlıdır. Gönderdiğiniz alanlar metin olmalı ve şu uzunlukları aşmamalıdır:

• Tanımlanmamış bir alan gönderirseniz (ör. buyer.phone) istek reddedilir.

buyer.id ile customerId farkı

İki alan da "müşteri kimliği" gibi görünür, ama farklı işler görür ve birbirinin yerine kullanılmaz: biri gönderildiğinde diğeri ondan doldurulmaz.

customerId şu yerlerde kullanılır:

• Ödeme listeleme: GET /payments?customerId=… yalnız o müşterinin ödemelerini döner; bkz. Ödeme Listeleme.
• Kart saklama: Ödemede kaydedilen kart müşteri anahtarının altına saklanır ve bu anahtar customerId'dir. Checkout Formu'nda farklı bir anahtar kullanmak isterseniz cardUserKey gönderin; göndermezseniz customerId kullanılır. Kayıtlı kartları GET /payments/cards?cardUserKey=… ile aynı anahtarla listelersiniz. Ödemede müşteri anahtarı yoksa kart saklanmaz, ödeme yine yapılır. Ayrıntı: Kart Saklama.
• Cüzdanla ödeme: Alıcı customerId ile tanımlanır; bkz. Cüzdanla Öde › Alıcı kimliği.

Neden gönderilmeli

• Ödeme kuruluşu: buyer bilgileri ödeme kuruluşuna iletilir.
• Risk değerlendirmesi: buyer.id ve buyer.email alıcının kimliği olarak değerlendirilir. buyer.registrationDate, alıcının sizde yeni bir müşteri olup olmadığını belirler. Alıcının ülkesi fatura adresinden, fatura adresi yoksa teslimat adresinden, o da yoksa buyer.country'den okunur.
• Yöntem alanları (Payment): POST /payments/direct/payment isteğinde yöntem bloğundaki bir alanı göndermezseniz, alanın prefill tanımındaki alıcı verisi kullanılır: buyer.gsmNumber, buyer.email, buyer.identityNumber, buyer.name ya da buyer.surname. Örneğin Faturana Yansıt'ta mobileBilling.gsmNumber gönderilmezse buyer.gsmNumber kullanılır. Bkz. Yöntemleri Listeleme › Yöntem alanları.

Doğrulama hataları

buyer içindeki bir hata 400 VALIDATION_ERROR döner. details.errors[] önce buyer girdisini, ardından hatalı alanın noktalı yolunu verir:

{
  "status": "failure",
  "code": "VALIDATION_ERROR",
  "message": "Doğrulama hatası — gönderilen alanları kontrol edin.",
  "statusCode": 400,
  "requestId": "4b0e6c1a-2f3d-4e5a-9b8c-7d6e5f4a3b2c",
  "details": {
    "errors": [
      { "field": "buyer", "errors": [] },
      { "field": "buyer.email", "errors": ["email must be an email"] }
    ]
  }
}

• buyer girdisi her zaman ilk sıradadır; hatanın nedeni ondan sonra gelen yol girdilerindedir.
• Kodunuzda message'a göre değil code'a ve field'a göre dallanın. Hata zarfı: Hatalar.

Devamı

• Sipariş Bilgileri: uçlar ve üç bilgiyi birlikte gösteren örnek istek
• Adres Bilgileri: teslimat ve fatura adresi
• Kart Saklama: müşteri anahtarıyla kart kaydı