Adres Bilgileri

Ödeme isteğinde iki adres gönderebilirsiniz:

shippingAddress: siparişin teslim edileceği adres.
billingAddress: siparişin faturalandığı adres.

İkisi aynı yapıdadır ve ikisi de isteğe bağlıdır.

Adresi alan uçlar

Uç	`shippingAddress`	`billingAddress`
`POST /payments/intents`, `POST /payments/marketplace/intents` (Checkout Formu)	Var	Var
`POST /payments/direct/payment` (Payment)	Var	Var
`POST /payments/marketplace/2d`, `/marketplace/3d` (Pazaryeri)	Var	Var

Adres kuralları bu uçların hepsinde aynıdır. Linkle Ödeme adres nesnesi almaz; alıcının adresini linkin prefill alanıyla verebilirsiniz, bkz. Link Oluşturma.

Alanlar

shippingAddress ve billingAddress aynı yapıdadır. Nesneyi gönderirseniz beş alan da zorunludur.

Alan	Tip	Örnek
`contactName`	string	`Ada Yılmaz`
`address`	string	`Altunizade Mah. …`
`city`	string	`İstanbul`
`country`	string	`Turkey`
`zipCode`	string	`34742`

Zorunluluk

İki nesne de isteğe bağlıdır. Birini, ikisini ya da hiçbirini gönderebilirsiniz.
Gönderdiğiniz nesnede contactName, address, city, country ve zipCode dolu metin olmalıdır. Boş metin de eksik sayılır. Bu kural Checkout Formu intent'i dahil her uçta geçerlidir.
Tanımlanmamış bir alan gönderirseniz (ör. district) istek reddedilir.

İki adresin farkı

	`shippingAddress`	`billingAddress`
Anlamı	Siparişin teslim edildiği adres	Siparişin faturalandığı adres
Ödeme kuruluşuna	Yalnız `billingAddress` gönderilmediyse iletilir	Gönderildiyse iletilir
Risk değerlendirmesinde ülke	Yalnız `billingAddress` gönderilmediyse okunur	Gönderildiyse önce bu okunur

Ödeme kuruluşuna tek bir adres iletilir: billingAddress; gönderilmediyse shippingAddress.
Risk değerlendirmesinde siparişin ülkesi billingAddress.country'den, yoksa shippingAddress.country'den okunur. İki adres de yoksa alıcının ülkesi için buyer.country kullanılır; bkz. Alıcı Bilgileri.

Hangisini ne zaman gönderin

Fiziksel ürün teslim ediyorsanız (kalemlerde itemType: "PHYSICAL"): teslimat adresini shippingAddress ile gönderin. Fatura başka bir adrese kesiliyorsa billingAddress'i de gönderin; ödeme kuruluşuna ve risk değerlendirmesine fatura adresi gider.
Teslimat yoksa (dijital ürün ya da hizmet, itemType: "VIRTUAL"): shippingAddress göndermeniz gerekmez; adres bilginiz varsa billingAddress ile gönderin.
Teslimat ve fatura adresi aynıysa aynı değerleri iki nesnede de gönderebilirsiniz.

Doğrulama hataları

Adresteki bir hata 400 VALIDATION_ERROR döner. details.errors[] önce nesnenin girdisini (shippingAddress ya da billingAddress), 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": "billingAddress", "errors": [] },
      { "field": "billingAddress.district", "errors": ["property district should not exist"] },
      { "field": "billingAddress.city", "errors": ["city should not be empty"] }
    ]
  }
}

Durum	`field`
Alan eksik ya da boş	Alanın yolu: `shippingAddress.zipCode`, `billingAddress.city` …
Tanımlanmamış alan	Alanın yolu: `billingAddress.district`; mesaj `property district should not exist`
Adres bir nesne değil	`shippingAddress` ya da `billingAddress`; nedeni bu girdinin kendi `errors` listesindedir

Nesnenin girdisi her zaman önce gelir; 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
Alıcı Bilgileri: buyer ve customerId
Sepet Kalemleri: kalemler ve itemType

Alıcı Bilgileri Genel Bakış