İstek ve Yanıt Biçimi

İstek

• Gövde JSON'dur; alan adları snake_case yazılır.
• Alanlar uca göre bir grup nesnesinin altında gönderilir: transaction, customer, card, order, subscription, product, saved_card.
• Şu nesnelerde tanımlı olmayan bir anahtar gönderilirse istek 422 ile reddedilir: ödeme, sipariş, abonelik ve save-card isteklerindeki customer; order.items[]; subscription.items[]; product.

Alan kuralları

Kural	Ayrıntı
Tutar	String, ^[0-9]+([.][0-9]{1,2})?$: "450" ya da "450.00". Virgül, binlik ayırıcı ve üslü yazım reddedilir.
Para birimi	TRY, USD, EUR, GBP. Gönderilmezse TRY.
channel_reference	Sizin sisteminizdeki kimlik. En çok 255 karakter. Ödeme, sipariş ve aboneliğin channel_reference alanı en az bir rakam içermelidir (SIP reddedilir, SIP1 kabul edilir).
URL alanları	callback_url, success_url, cancel_url, webhook_url: http ya da https, en çok 2048 karakter.
Token alanları	UUID.
Metin alanları	Aksi belirtilmedikçe en çok 255 karakter.

customer nesnesi

Ödeme, sipariş, abonelik ve save-card isteklerinde müşteri eksiksiz gönderilir. Müşteri, kanal içinde channel_reference ile tanınır; gönderilen bilgiler müşterinin güncel hâli olarak kaydedilir.

Alan	Tip	Zorunlu	Açıklama
channel_reference	string	evet	Müşterinin sizin sisteminizdeki kimliği.
firstname	string	evet
lastname	string	evet
email	string	evet	Geçerli e-posta adresi.
phone	string	evet
address	string	evet
district	string	evet	İlçe.
province	string	evet	İl.
country	string	evet
tax	object	hayır	Kurumsal fatura bilgisi. Gönderilirse üç alanı da zorunludur.
tax.company_title	string	koşullu	Şirket unvanı.
tax.tax_number	string	koşullu	Vergi numarası.
tax.tax_office	string	koşullu	Vergi dairesi.

"customer": {
  "channel_reference": "musteri-88",
  "firstname": "Ahmet",
  "lastname": "Yılmaz",
  "email": "[email protected]",
  "phone": "05551112233",
  "address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
  "district": "Çankaya",
  "province": "Ankara",
  "country": "Türkiye"
}

Yanıt

Her yanıt bir result nesnesiyle başlar; uca özel alanlar yanında gelir.

{
  "result": {
    "successful": true,
    "message": null
  },
  "transaction": {
    "token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d",
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14",
    "channel_reference": "SIP-10231"
  },
  "customer": {
    "channel_reference": "musteri-88"
  },
  "conversion": null
}

Alan	Tip	Açıklama
result.successful	boolean	İşlemin sonucu.
result.message	string | null	successful false ise nedeni; true ise null.
result.errors	object	Yalnızca 422 yanıtlarında: alan yolu → mesaj listesi.

200 yanıtında result.successful: false, isteğin kabul edilip işlendiğini ama sağlayıcının işlemi yapmadığını gösterir (ör. banka ödemeyi reddetti). İsteğin kendisinin reddedilmesi 4xx ile döner. Ayrıntılar: Hatalar.

Ödeme hesabı seçimi

payment_provider_token alanı ödeme, sipariş, abonelik, save-card ve retrieve-bin isteklerinde isteğe bağlıdır.

Durum	Kullanılan hesap
saved_card_token ile ödeme	Kartın saklandığı hesap. Yönlendirme kuralları ve varsayılan hesap uygulanmaz; payment_provider_token gönderilemez.
payment_provider_token gönderildi	Gönderilen hesap. Yönlendirme kuralları uygulanmaz.
Gönderilmedi, kart numarasıyla ödeme	Çalışma alanının panelde tanımlı yönlendirme kurallarının seçtiği hesap; kural yoksa ya da hiçbiri tutmazsa varsayılan hesap.
Gönderilmedi, save-card	Varsayılan hesap.

• Yönlendirme kuralları kartın ilk hanelerine (banka, şema, program, tip, ticari kart), tutara ve para birimine göre tanımlanır. Kuralın hesabı isteği karşılayamıyorsa (ödeme türü, para birimi ya da kart saklama desteklenmiyorsa) kural atlanır.
• Seçilen ya da gönderilen hesabın sağlayıcısı istenen işlemi desteklemiyorsa istek, ilgili payment_provider_token alanında 422 ile reddedilir.