Müşteriler, fatura bilgileri ve kalemler

Fatura bilgileri zorunludur

Kart ağları ve acquirer'lar ödemeyi kimin yaptığını bilmek ister. Bir kart ödemesini onaylamak için platformun eksiksiz fatura bilgilerine ihtiyacı vardır:

• name
• address.line1
• address.city
• address.country (ISO 3166 alpha-2, örneğin TR)

Bunları ödemeyi oluştururken veya onaylarken payment_method_data[billing_details] içinde gönderin. Canlı kurulumlarda bu bilgiler olmadan yapılan ödeme, istek bankaya ulaşmadan 400 billing_details_required (param: payment_method_data[billing_details]) ile reddedilir. Sandbox kurulumları yalnızca uyarı verir (uyarı Geliştiriciler → İstek kayıtları bölümünde görünür); bu nedenle bunu entegrasyon sırasında düzeltin. Türkiye'de address.state il, address.city ise ilçe veya şehirdir.

Ödeme kayıtlı bir müşteri için yapılıyorsa, müşterinin verilerini yeniden yazmak yerine oluşturma veya onaylama isteğinde billing_details_from_customer: true ile kopyalayabilirsiniz. Açıkça gönderilen fatura bilgileri önceliklidir.

{
  "name": "Ayse Yilmaz",
  "email": "ayse@example.com",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  }
}

Ticari bir gerekçeniz varsa hesabınızda fatura kuralından onaylı ve süreli bir muafiyet tanımlanabilir. Ödeme kuruluşuna başvurun; bu, incelenen bir ayardır, API seçeneği değildir.

Müşteriler

Müşteri, size ödeme yapan kişinin hesabınıza ait kaydıdır. Bir müşteri oluşturun, ardından ödemelerde ve kayıtlı kartlarda customer olarak ona başvurun.

{
  "email": "ayse@example.com",
  "name": "Ayse Yilmaz",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  },
  "tax_id": "10000000146",
  "preferred_locales": ["tr-TR"],
  "metadata": {"crm_id": "C-2210"}
}

curl -X POST https://pay.example.com/v1/customers \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: customer-C-2210" \
  -H "Content-Type: application/json" \
  -d '{"email": "ayse@example.com", "name": "Ayse Yilmaz"}'

{
  "id": "cus_01J9ZQ9D3F5H7K9M2P4R6T8W1Y",
  "object": "customer",
  "email": "ayse@example.com",
  "name": "Ayse Yilmaz",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  },
  "tax_id": {"type": "tr_tckn", "masked": "*********46"},
  "preferred_locales": ["tr-TR"],
  "metadata": {"crm_id": "C-2210"},
  "created": 1790000100
}

• tax_id, TCKN (11 hane) veya VKN (10 hane) olabilir. Şifrelenmiş olarak saklanır ve yalnızca maskeli döndürülür.
• Güncellemek için POST /v1/customers/{id} (veya PATCH) kullanın; null göndermek ilgili alanı temizler. Listelemek için GET /v1/customers (e-postaya göre filtrelenebilir); kayıtlı kartları GET /v1/payment_methods?customer=cus_… ile okuyun.
• Anlık görüntüler (snapshot): ödeme, ödemenin yapıldığı andaki müşteri verisinin anlık görüntüsü olan customer_details alanını saklar (onaya kadar yenilenir, sonra dondurulur). Müşteriyi güncellemek veya silmek geçmiş ödemeleri asla değiştirmez. expand[]=customer güncel müşteriyi döndürür.
• Bir müşteriyi silmek (DELETE /v1/customers/{id}) kişisel verilerini siler. Ödemeler cus_ kimliğini ve kendi anlık görüntülerini korur.

Kalemler

Kalemler (line_items), müşterinin ne satın aldığını tanımlar. Bazı acquirer'lar sepet bilgisi ister; bu yüzden mümkün olduğunda gönderin. Hesabınız kalem gerektiriyorsa ve ödemede kalem yoksa ödeme 400 line_items_required (param: line_items) ile başarısız olur; aksi halde bir uyarı kaydedilir.

Her kalem ya bir katalog ürünü ile bir adettir ya da satır içi fiyat verisi ile bir adettir. Tüm kalemlerin amount_subtotal toplamı (unit_amount × quantity) ödeme amount değerine (ana tutar) eşit olmalıdır; aksi halde çağrı 400 line_items_amount_mismatch ile başarısız olur. En fazla 100 kalem gönderilebilir.

{
  "amount": 35000,
  "currency": "try",
  "confirm": true,
  "customer": "cus_01J9ZQ9D3F5H7K9M2P4R6T8W1Y",
  "billing_details_from_customer": true,
  "payment_method": "pm_01J9ZQA2B4C6D8E1F3G5H7J9K2",
  "return_url": "https://shop.example.com/pay/return",
  "line_items": [
    {"price_data": {"unit_amount": 10000, "product_data": {"name": "Notebook", "type": "physical", "category": "Stationery", "sku": "NB-01"}}, "quantity": 2},
    {"product": "prod_01J9ZQB5C7D9F2H4K6M8P1R3T5", "quantity": 1}
  ],
  "shipping": {
    "name": "Ayse Yilmaz",
    "address": {"line1": "Bagdat Caddesi 1", "city": "Kadikoy", "country": "TR"}
  }
}

Burada defterler 2 × 10000 = 20000 tutarındadır ve katalog ürününün unit_amount değeri 15000 olduğundan kalemlerin toplamı 35000 eder.

Katalog ürünleri (/v1/products) bir ad, tür (physical, digital, service), kategori, SKU ve varsayılan bir unit_amount içerir. Bir ödemenin kalemlerini GET /v1/payment_intents/{id}/line_items veya expand[]=line_items ile okuyun.

Kayıtlarda kişisel veriler

İstek kayıtlarınız müşteri iletişim verilerini maskeli biçimde gösterir (kısmi e-posta, telefon ve adres; fatura bilgilerindeki adlar maskelenir; vergi kimlikleri gizlenir). Kart numaraları ve CVC hiçbir yerde görünmez.