Ana içeriğe geç

İstek ve Yanıt Biçimi

İstek​

  • Bütün uçlar POST ile ve JSON gövdeyle çağrılır; sorgu uçları dahil.
  • Alan adları snake_case yazılır. Alanlar uca göre bir grup nesnesinin altında gönderilir: transaction, customer, card, order, subscription, payment_link, saved_card, bank_account.
  • order, subscription, payment_link, customer ve update-saved-card isteğindeki saved_card nesnelerinde tanımlı olmayan bir anahtar gönderilirse istek 422 ile reddedilir. Kalem nesneleri için de aynısı geçerlidir.
  • Varsayılanı olan bir alan gönderilmeyebilir; gönderilmezse varsayılanı uygulanır.
  • bank_account nesnesinde de tanımlı olmayan bir anahtar 422 alır.
  • Adreste token taşıyan update-* ve delete-* isteklerinde aynı token gövdede token alanında da gönderilir; ikisi aynı olmalıdır.

Alan kuralları​

KuralAyrıntı
TutarString, nokta ayraçlı, en çok iki ondalık: "450", "450.5", "450.50". Virgül, binlik ayırıcı ve eksi işaret reddedilir. Sıfırdan büyük olmalı; bir ödemede, kalem birim fiyatında ve kalemlerin toplamında en fazla 10000000.00.
Para birimiTRY, USD, EUR, GBP. Gönderilmezse TRY (ödeme linkinde zorunludur).
TaksitTRY ile istenip TRY olarak çekilen ödemede 1–12; diğerlerinde 1.
referenceSizin sisteminizdeki referans. En çok 255 karakter. Ödeme, sipariş, abonelik ve ödeme linkinin reference alanı en az bir rakam içermelidir (SIP reddedilir, SIP1 kabul edilir); referansın rakamları bankaya giden sipariş numarasında kullanılır. Referans tekil değildir: aynı referans birden çok kayıtta bulunabilir (Aynı referansla tekrarlanan create-* istekleri).
URL alanlarıcallback_url, success_url, cancel_url: https ile başlayan, herkese açık bir adres (yerel ve özel ağ adresleri reddedilir); en çok 2048 karakter. Sandbox'ta http ve localhost da kabul edilir. Kalem görseli (image): http ya da https, en çok 2048 karakter.
Token alanlarıUUID. Bir kaydı tekil olarak adlandıran tek değer token'dır; update-* uçları ve webhook gövdeleri kaydı token'la anar.
Tarih alanlarıİstekte YYYY-MM-DD, çalışma alanının saat diliminde (created_from, created_to, payment_link.expires_at). retrieve-bank-transactions created_from / created_to ile bankanın kayıt gününü süzer. Yanıtta ISO 8601 UTC: 2026-10-02T09:15:30.000000Z.
Metin alanlarıAksi belirtilmedikçe en çok 255 karakter.

customer nesnesi​

"customer": {
"reference": "musteri-88",
"billing_address": {
"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": "TR",
"company_title": "Örnek A.Ş.",
"tax_number": "1234567890",
"tax_office": "Çankaya"
},
"shipping_address": {
"firstname": "Ahmet",
"lastname": "Yılmaz",
"address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
"district": "Çankaya",
"province": "Ankara",
"country": "TR"
}
}
AlanTipAçıklama
referencestringMüşterinin sizin sisteminizdeki referansı. Çalışma alanınızdaki müşteri bu referansla tutulur; kartlar bu müşterinin altında saklanır.
billing_addressobjectFatura adresi. Kişi alanları: firstname (Ad), lastname (Soyad), email (geçerli e-posta), phone, address, district (ilçe), province (il), country.
billing_address.company_title, .tax_number, .tax_officestringFirma ünvanı, vergi numarası, vergi dairesi. İsteğe bağlı; biri gönderilirse üçü de gönderilir.
shipping_addressobjectGönderim adresi; fatura adresiyle aynı kişi alanları (firma alanları yok).

Hangi alanın zorunlu olduğu uca göre değişir:

Uçreferencebilling_addressshipping_address
secure-payment, regular-paymentKart saklanacaksa ya da kayıtlı kartla ödeniyorsa zorunluZorunlu, sekiz kişi alanı da zorunlu; Varsayılan Ödeyen açıksa isteğe bağlıGönderilmez
create-saved-cardZorunluZorunlu, sekiz kişi alanı da zorunlu; Varsayılan Ödeyen açıksa isteğe bağlıGönderilmez
create-order, update-orderİsteğe bağlıİsteğe bağlı, her alan isteğe bağlıİsteğe bağlı
create-subscriptionZorunluİsteğe bağlıİsteğe bağlı
update-subscriptionİsteğe bağlı, silinemez; ilk dönem ödendikten sonra customer gönderilemezİsteğe bağlıİsteğe bağlı

Sipariş ve abonelikte gönderilen müşteri alanları ödeme sayfasındaki formu önceden doldurur; gönderilmeyenler ödeme sayfasında alınır. update-* isteğinde gönderilen alanlar mevcut bilginin üzerine yazılır, gönderilmeyenler korunur.

Müşteri kaydı​

Çalışma alanınızda müşteri yalnızca customer.reference gönderildiğinde açılır ve yalnızca başarılı bir ödemeyle yazılır:

  • Ödeme başarılı olduğunda, ödemedeki fatura bilgileriyle bu referanstaki müşteri açılır; varsa güncellenir. Boş gelen alanlar mevcut değerleri silmez. Varsayılan Ödeyen'den doldurulan alanlar müşteriye yazılmaz.
  • Sipariş ya da abonelikte referans ödeme sayfasından önce alınır; müşteri, sayfadaki ödeme başarılı olunca yazılır. Ödenmemiş bir sipariş ya da reddedilen bir ödeme müşteri açmaz.
  • Abonelik yenilemeleri müşteriyi güncellemez.
  • create-saved-card, kart sağlayıcıda saklandığında müşteriyi yazar.
  • customer.reference gönderilmeyen ödeme ya da sipariş müşteri açmaz; ödeyenin bilgisi yalnızca işlemde kalır. Ödeme linkinde müşteri gönderilmez. Kart saklamak ve abonelik açmak için customer.reference zorunludur.

Varsayılan Ödeyen​

İsteğinizde göndermediğiniz ama ödeme sağlayıcısının zorunlu tuttuğu fatura bilgilerini Varsayılan Ödeyen tamamlar. Panelde Ödeme Ayarları → Varsayılan Ödeyen sayfasından açılır: Varsayılan ödeyeni açmak. Ayar kapalı gelir; kapalıyken ödeme ve kart saklama isteklerinde sekiz kişi alanının hepsi zorunludur.

Açıkken:

  • secure-payment, regular-payment ve create-saved-card isteklerinde billing_address ve sekiz kişi alanının her biri isteğe bağlıdır. Ödemede customer nesnesinin kendisi de gönderilmeyebilir; kart saklarken customer.reference yine zorunludur.
  • Sipariş, abonelik ve ödeme linkinin ödeme sayfası değişmez: sayfadaki fatura alanlarının hepsi yine zorunludur.
  • Kart saklama dahil, gönderilmeyen ya da boş gelen her kişi alanı ödeme sağlayıcısına varsayılan ödeyenin değeriyle gider. Gönderilen alan değiştirilmez: yalnızca firstname ve email gönderirseniz bu ikisi sizin değerinizle, diğer altısı varsayılan ödeyenden gider.
  • Gönderilen alanlar aynı kurallarla doğrulanır; province gönderiyorsanız country alanını da gönderin, il ülkeye göre kontrol edilir. Firma alanları ve shipping_address doldurulmaz.
  • Ödeme yanıtındaki ve işlem nesnesindeki customer.billing_address, varsayılan ödeyenden doldurulan alanları da taşır; panelde ödemenin müşteri bilgilerinde ve size giden ödeme e-postalarında da bu değerler görünür. Sipariş, abonelik ve link ödemesi yanıtlarındaki customer yalnızca gönderilen ve ödeme sayfasında girilen bilgiyi taşır.
  • Müşteri kaydı yalnızca gönderilen alanlarla yazılır. Müşteriye giden e-postalar varsayılan ödeyenin e-postasına gitmez.

Ayar her ödemede ve kart saklamada o anki hâliyle uygulanır; Test ve Canlı modda aynıdır. Ayarı kapattığınızda sekiz alan hemen yeniden zorunlu olur ve eksik alanlı istekler 422 alır.

Yanıttaki customer​

Sipariş ve abonelik yanıtlarında customer şu biçimdedir; ne referans ne adres verildiyse null'dır. Referans gönderilmediyse reference null'dır:

"customer": {
"reference": "musteri-88",
"billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" },
"shipping_address": null
}

billing_address yalnızca dolu alanları (firma alanları dahil) taşır; shipping_address gönderim adresi yoksa null'dır. Ödeme yanıtlarındaki customer ödeme anındaki bilgidir: Ödeme yanıtı. Kayıtlı kart yanıtlarındaki customer yalnızca reference taşır.

Kalemler​

Sipariş, abonelik ve ödeme linki tutarı gönderilmez; kalemlerden hesaplanır. İki istisna vardır:

  • Tutar tipi custom, predefined ya da predefined_and_custom olan ödeme linkinde items yok sayılır; tutarı ödeyen ödeme sayfasında seçer ya da girer. Bkz. create-payment-link.
  • Ödeme sayfasında kupon uygulanırsa indirim kalemlerden düşülür: Kupon ve discount.
"items": [
{ "reference": "SKU-1", "name": "Kulaklık", "image": "https://magazam.com/img/kulaklik.jpg", "quantity": 1, "unit_amount": "1200.00", "tax_rate": "20" }
]
AlanTipZorunluAçıklama
namestringevetKalemin adı. En çok 255 karakter.
quantityintegerevet1–9999.
unit_amountstring | numberevetKDV dahil birim fiyat, en çok iki ondalık. En az 0.01, en fazla 10000000.00.
tax_ratestring | numberhayırKDV oranı, 0–100, en çok iki ondalık. Gönderilmezse 0 (KDV yok).
referencestringhayırKalemin sizin sisteminizdeki referansı. save_as_product true ise zorunlu.
save_as_productbooleanhayırtrue ise kalem çalışma alanınızın ürünlerine bu reference ile kaydedilir. Gönderilmezse ürünlere dokunulmaz. Yanıtta dönmez.
imagestringhayırÖdeme sayfasında kalemin yanında gösterilen görselin adresi.

KDV birim fiyatın içinden ayrılır: %20 KDV'li 120.00'lik bir kalemin 100.00'ü ara toplama, 20.00'si KDV'ye yazılır. Kalem sayısı 1–100'dür.

Gönderim yöntemleri​

Gönderim yöntemleri istekte gönderilmez; panelde Gönderim sayfasında, gönderdikleri ülke ve illerle birlikte tanımlanır. Sipariş ya da abonelik requires_shipping: true ile açıldıysa ödeme sayfası gönderim adresini alır ve ödeyene o adrese gönderen yöntemleri sunar. Seçilen yöntem yanıtta shipping_method alanında döner (reference, title, KDV dahil amount, tax_rate) ve ücreti tutara eklenir.

Kupon ve discount​

API'de kupon kodu alanı ve kupon ucu yoktur. Kupon kodu ödeme sayfasında girilir; uygulanan kupon sipariş, abonelik ve ödeme linki ödemesi yanıtlarında discount alanında döner:

"discount": { "code": "YAZ10", "amount": "120.00" }
AlanTipAçıklama
discountobject | nullUygulanan kupon; kupon yoksa null.
discount.codestringÖdeme sayfasında girilen kupon kodu.
discount.amountstringKalemlerden düşülen tutar, iki ondalıklı, kaydın para biriminde.
  • Siparişte ve ödeme linki ödemesinde subtotal, tax_amount ve amount indirim düşülmüş değerlerdir. Siparişte indirim gönderim ücretinden düşülmez.
  • Abonelikte discount ilk ödemede uygulanan kupondur. Aboneliğin subtotal, tax_amount ve amount alanları indirimsizdir; ilk dönem için çekilen tutar renewal.amount alanındadır.
  • Webhook gövdeleri discount taşımaz; kupon bilgisi ilgili retrieve-* ucuyla alınır.

Yanıt​

Her yanıt bir result nesnesiyle başlar; uca özel alanlar yanında gelir. Yanıtlar imzalıdır: Yanıtın imzasını doğrulamak.

{
"result": {
"successful": true,
"message": null
},
"order": { "...": "..." }
}
AlanTipAçıklama
result.successfulbooleanİşlemin sonucu.
result.messagestring | nullsuccessful false ise nedeni (Türkçe); true ise null.
result.errorsobjectYalnızca 422 yanıtlarında: alan yolu → mesaj listesi.

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

Sayfalama​

Bütün sorgu uçları (retrieve-payments, retrieve-orders, retrieve-subscriptions, retrieve-payment-links, retrieve-link-payments, retrieve-saved-cards, retrieve-bank-transactions) her zaman sayfalıdır: liste yalnızca istenen sayfanın kayıtlarını taşır ve yanıtta her zaman pagination vardır. Sayfa isteğe bağlı page ve per_page alanlarıyla seçilir.

AlanTipAçıklama
pageintegerSayfa, 1'den başlar. Gönderilmezse 1.
per_pageintegerSayfadaki kayıt sayısı, 1–250. Gönderilmezse: page gönderildiyse 50, page de gönderilmediyse 250.
  • İkisi de gönderilmezse ilk sayfa 250 kayıtla döner. Sorgunuz 250'den fazla kayıtla eşleşiyorsa yalnızca ilk 250'si gelir; pagination.total ve pagination.last_page kalanını gösterir. Yoğun bir çalışma alanında 7 günde binlerce kayıt olabilir; sayfa sayfa sorun.
  • Sayfalar token, referans ve tarih aralığıyla birlikte kullanılabilir. Sıralama değişmez: eskiden yeniye (kayıtlı kartlarda varsayılan kart önce).
  • retrieve-bank-accounts sayfa almaz.
{
"result": { "successful": true, "message": null },
"created_from": "2026-09-26",
"created_to": "2026-10-02",
"pagination": { "page": 1, "per_page": 50, "total": 132, "last_page": 3 },
"payments": [ { "...": "..." } ]
}
AlanTipAçıklama
pagination.pageintegerBu sayfa.
pagination.per_pageintegerSayfadaki en fazla kayıt sayısı.
pagination.totalintegerBütün sayfalardaki kayıt sayısı.
pagination.last_pageintegerSon sayfa; kayıt yoksa 1. last_page'ten büyük bir sayfa boş liste döner.

250'den büyük per_page ya da 1'den küçük page 422 alır. Bütün kayıtları okumak için page'i pagination.last_page'e kadar artırın:

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

use Gurmehub\Odemehub\Request\RetrievePayments;

$page = 1;

do {
$list = $client->retrievePayments(RetrievePayments::between('2026-09-26', '2026-10-02')->withPage($page++, 100));

foreach ($list->payments as $payment) {
// ...
}
} while ($list->pagination->hasMorePages());

Aynı referansla tekrarlanan create-* istekleri​

reference tekil değildir. create-order, create-subscription ve create-payment-link her çağrıda yeni bir kayıt açar ve yeni bir token döndürür; aynı reference daha önce gönderilmiş olsa da. Aynı referanslı önceki kayıtlar değiştirilmez: ödenmemiş olan ödenmemiş, ödenmiş olan ödenmiş kalır. Önceki kayıt ödenmiş olsa ya da üzerinde sonuçlanmamış bir ödeme bulunsa da tekrarlanan referans 422 döndürmez.

  • Sipariş ya da aboneliğin ödemesi tamamlanmadıysa aynı numarayla create-order / create-subscription yeniden çağrılabilir ve ödeyen yeni yanıttaki checkout_url adresine yönlendirilir.
  • Var olan bir kaydı değiştirmek için token'ıyla update-order, update-subscription ya da update-payment-link kullanılır. update-order ve update-subscription ödenmiş kaydı ve üzerinde sonuçlanmamış ödeme bulunan kaydı reddeder.
  • retrieve-orders, retrieve-subscriptions ve retrieve-payment-links reference ile sorgulandığında o referanstaki kayıtların hepsini döndürür; kayıtlar token ile ayırt edilir, sipariş ve abonelikte status ödenmiş olanı gösterir.
  • Her create-* yanıtındaki token saklanmalı ve kayıtlar token'la eşleştirilmelidir. Webhook gövdeleri kaydı yalnızca token'la anar.

"Sonuçlanmamış ödeme", son 15 dakika içinde başlamış ve henüz sonuçlanmamış ödemedir. Ödeme uçları (secure-payment, regular-payment) da aynı reference ile gönderilen her isteği yeni bir ödeme denemesi olarak işler.

Ödeme hesabı seçimi​

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

DurumKullanılan hesap
saved_card_token ile ödemeKartın saklandığı hesap. Yönlendirme kuralları ve varsayılan hesap uygulanmaz; payment_provider_token gönderilemez.
payment_provider_token gönderildiGö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, sipariş, abonelik ya da ödeme linkiHesap ödeme anında, ödeme sayfasındaki kartla aynı kurallara göre seçilir.
Gönderilmedi, create-saved-cardVarsayılan hesap.
  • Yönlendirme kuralları panelde Ödeme Ayarları → Gate altında tanımlanır; her çalışma alanında açıktır, modül gerektirmez. Kurallar kartın bankasına, şemasına, programına, tipine, ticari kart olup olmadığına, tutara ve para birimine göre çalışır ve sırayla denenir; ödemenin karşıladığı ilk kural hesabı belirler. 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.
  • Hesap gönderilmediyse ve çalışma alanının varsayılan hesabı yoksa istek 422 döner: Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.