İstek ve Yanıt Biçimi
İstek
- Bütün uçlar
POSTile ve JSON gövdeyle çağrılır; sorgu uçları dahil. - Alan adları
snake_caseyazı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,customerveupdate-saved-cardisteğindekisaved_cardnesnelerinde tanımlı olmayan bir anahtar gönderilirse istek422ile reddedilir. Kalem nesneleri için de aynısı geçerlidir.- Varsayılanı olan bir alan gönderilmeyebilir; gönderilmezse varsayılanı uygulanır.
bank_accountnesnesinde de tanımlı olmayan bir anahtar422alır.- Adreste token taşıyan
update-*vedelete-*isteklerinde aynı token gövdedetokenalanında da gönderilir; ikisi aynı olmalıdır.
Alan kuralları
| Kural | Ayrıntı |
|---|---|
| Tutar | String, 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 birimi | TRY, USD, EUR, GBP. Gönderilmezse TRY (ödeme linkinde zorunludur). |
| Taksit | TRY ile istenip TRY olarak çekilen ödemede 1–12; diğerlerinde 1. |
reference | Sizin 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",
"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"
}
}
| Alan | Tip | Açıklama |
|---|---|---|
reference | string | Müşterinin sizin sisteminizdeki referansı. Çalışma alanınızdaki müşteri bu referansla tutulur; kartlar bu müşterinin altında saklanır. |
billing_address | object | Fatura 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_office | string | Firma ünvanı, vergi numarası, vergi dairesi. İsteğe bağlı; biri gönderilirse üçü de gönderilir. |
shipping_address | object | Gönderim adresi; fatura adresiyle aynı kişi alanları (firma alanları yok). |
Hangi alanın zorunlu olduğu uca göre değişir:
| Uç | reference | billing_address | shipping_address |
|---|---|---|---|
secure-payment, regular-payment | Kart saklanacaksa ya da kayıtlı kartla ödeniyorsa zorunlu | Zorunlu, sekiz kişi alanı da zorunlu; Varsayılan Ödeyen açıksa isteğe bağlı | Gönderilmez |
create-saved-card | Zorunlu | Zorunlu, 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-subscription | Zorunlu | İ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.referencegö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çincustomer.referencezorunludur.
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-paymentvecreate-saved-cardisteklerindebilling_addressve sekiz kişi alanının her biri isteğe bağlıdır. Ödemedecustomernesnesinin kendisi de gönderilmeyebilir; kart saklarkencustomer.referenceyine 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
firstnameveemailgönderirseniz bu ikisi sizin değerinizle, diğer altısı varsayılan ödeyenden gider. - Gönderilen alanlar aynı kurallarla doğrulanır;
provincegönderiyorsanızcountryalanını da gönderin, il ülkeye göre kontrol edilir. Firma alanları veshipping_addressdoldurulmaz. - Ö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ındakicustomeryalnı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",
"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,predefinedya dapredefined_and_customolan ödeme linkindeitemsyok 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" }
]
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
name | string | evet | Kalemin adı. En çok 255 karakter. |
quantity | integer | evet | 1–9999. |
unit_amount | string | number | evet | KDV dahil birim fiyat, en çok iki ondalık. En az 0.01, en fazla 10000000.00. |
tax_rate | string | number | hayır | KDV oranı, 0–100, en çok iki ondalık. Gönderilmezse 0 (KDV yok). |
reference | string | hayır | Kalemin sizin sisteminizdeki referansı. save_as_product true ise zorunlu. |
save_as_product | boolean | hayır | true ise kalem çalışma alanınızın ürünlerine bu reference ile kaydedilir. Gönderilmezse ürünlere dokunulmaz. Yanıtta dönmez. |
image | string | hayı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" }
| Alan | Tip | Açıklama |
|---|---|---|
discount | object | null | Uygulanan kupon; kupon yoksa null. |
discount.code | string | Ödeme sayfasında girilen kupon kodu. |
discount.amount | string | Kalemlerden düşülen tutar, iki ondalıklı, kaydın para biriminde. |
- Siparişte ve ödeme linki ödemesinde
subtotal,tax_amountveamountindirim düşülmüş değerlerdir. Siparişte indirim gönderim ücretinden düşülmez. - Abonelikte
discountilk ödemede uygulanan kupondur. Aboneliğinsubtotal,tax_amountveamountalanları indirimsizdir; ilk dönem için çekilen tutarrenewal.amountalanındadır. - Webhook gövdeleri
discounttaşımaz; kupon bilgisi ilgiliretrieve-*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": { "...": "..." }
}
| Alan | Tip | Açıklama |
|---|---|---|
result.successful | boolean | İşlemin sonucu. |
result.message | string | null | successful false ise nedeni (Türkçe); 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 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.
| Alan | Tip | Açıklama |
|---|---|---|
page | integer | Sayfa, 1'den başlar. Gönderilmezse 1. |
per_page | integer | Sayfadaki 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.totalvepagination.last_pagekalanı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-accountssayfa 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": [ { "...": "..." } ]
}
| Alan | Tip | Açıklama |
|---|---|---|
pagination.page | integer | Bu sayfa. |
pagination.per_page | integer | Sayfadaki en fazla kayıt sayısı. |
pagination.total | integer | Bütün sayfalardaki kayıt sayısı. |
pagination.last_page | integer | Son 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:
Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.
- PHP
- Node.js
- Python
- Java
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());
let page = 1;
let list;
do {
list = await client.retrievePayments({ createdFrom: '2026-09-26', createdTo: '2026-10-02', page: page++, perPage: 100 });
for (const payment of list.payments) {
// ...
}
} while (list.pagination?.hasMorePages());
from odemehub.request import RetrievePayments
page = 1
while True:
listing = client.retrieve_payments(RetrievePayments(created_from="2026-09-26", created_to="2026-10-02", page=page, per_page=100))
for payment in listing.payments:
...
if not listing.pagination.has_more():
break
page += 1
import com.odemehub.request.RetrievePayments;
int page = 1;
while (true) {
var list = client.retrievePayments(RetrievePayments.between("2026-09-26", "2026-10-02").page(page).perPage(100));
for (var payment : list.getPayments()) {
// ...
}
if (!list.getPagination().hasMorePages()) {
break;
}
page++;
}
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-subscriptionyeniden çağrılabilir ve ödeyen yeni yanıttakicheckout_urladresine yönlendirilir. - Var olan bir kaydı değiştirmek için token'ıyla
update-order,update-subscriptionya daupdate-payment-linkkullanılır.update-orderveupdate-subscriptionödenmiş kaydı ve üzerinde sonuçlanmamış ödeme bulunan kaydı reddeder. retrieve-orders,retrieve-subscriptionsveretrieve-payment-linksreferenceile sorgulandığında o referanstaki kayıtların hepsini döndürür; kayıtlartokenile ayırt edilir, sipariş ve aboneliktestatusödenmiş olanı gösterir.- Her
create-*yanıtındakitokensaklanmalı 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.
| 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, sipariş, abonelik ya da ödeme linki | Hesap ödeme anında, ödeme sayfasındaki kartla aynı kurallara göre seçilir. |
Gönderilmedi, create-saved-card | Varsayı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_tokenalanında422ile reddedilir. - Hesap gönderilmediyse ve çalışma alanının varsayılan hesabı yoksa istek
422döner:Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.