Ana içeriğe geç

Banka Hareketleri

Banka hesabınızın hareketleri, tek uçtan sizin sisteminizde. ödemehub eklediğiniz hesabın hareketlerini bankadan okur ve saklar; siz onları retrieve-bank-transactions ile işaretli tutar, karşı taraf IBAN'ı ve gönderenin açıklamasıyla alırsınız. Bankanın API'siyle siz konuşmazsınız: kimlik bilgilerini bir kez gönderirsiniz, okuma ve token yenileme ödemehub'dadır.

  1. Bankayı seçme — retrieve-banks eklenebilen bankaları ve her bankanın istediği kimlik bilgisi alanlarını (fields) döner.
  2. Hesabı ekleme — create-bank-account ile banka (provider), hesap adı, IBAN ve kimlik bilgilerini (settings) gönderirsiniz. ödemehub bilgileri önce bankada o IBAN için dener. Banka reddederse yanıt yine 200'dür: result.successful false, result.message bankanın mesajı, bank_account null; hesap eklenmez.
  3. Token'ı saklama — Yanıttaki bank_account.token'ı saklayın. Hesap API'de yalnızca bu token'la anılır.
  4. Hareketleri okuma — retrieve-bank-transactions ile hesap token'larını (bank_account_tokens) ve en fazla 7 günlük aralığı gönderirsiniz; hareketler sayfa sayfa gelir.

Ön koşullar​

  • Çalışma alanınızda Banka Hareketleri modülü açık olmalıdır; değilse bütün banka uçları 403 döner: Çalışma alanınızda bu modül kapalı; açtırmak için bizimle iletişime geçin. Banka uçları Api modülünü istemez.
  • Bir IBAN çalışma alanına bir kez eklenir. IBAN TR ile başlayan 26 karakter olmalıdır; boşluklar silinir, harfler büyütülür.
  • Banka hesaplarında test ve canlı ayrımı yoktur: hesap, çalışma alanının modundan bağımsız olarak bankadaki gerçek hesaptan okunur.

Eklenen hesaplar panelde Ödeme Ayarları → Banka Hesapları, hareketleri Banka Hareketleri sayfasında da görünür.

Enpara'dan kimlik bilgileri​

Enpara Şirketim internet bankacılığından API hizmetlerine başvurursunuz; client_id, client_secret, access token ve refresh token size e-postayla gelir. Dördü de settings nesnesinde, retrieve-banks yanıtındaki anahtarlarla gönderilir:

settings anahtarıEnpara'dan gelen
client_idClient ID
client_secretClient Secret
access_tokenAccess Token
refresh_tokenRefresh Token
  • ödemehub token'ları kendisi yeniler. Refresh token 90 gün kullanılmazsa Enpara'dan yeniden alınması gerekir; yenilerini update-bank-account ile gönderirsiniz.
  • Aynı client_id ile eklediğiniz hesaplar kimlik bilgilerini paylaşır: bir hesapta gönderdiğiniz yeni bilgiler, o client_id'yi kullanan diğer hesaplarınızda da geçerli olur.
  • Kimlik bilgileri hiçbir yanıtta dönmez.

Hesabı ekleme​

not

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

use Gurmehub\Odemehub\Request\CreateBankAccount;

$created = $client->createBankAccount(new CreateBankAccount(
provider: 'enpara',
name: 'Tahsilat Hesabı',
iban: 'TR33 0006 1005 1978 6457 8413 26',
settings: [
'client_id' => getenv('ENPARA_CLIENT_ID'),
'client_secret' => getenv('ENPARA_CLIENT_SECRET'),
'access_token' => getenv('ENPARA_ACCESS_TOKEN'),
'refresh_token' => getenv('ENPARA_REFRESH_TOKEN'),
],
));

$bankAccountToken = $created->bankAccount?->token; // banka reddettiyse null; mesajı $created->result->message

Hareketleri okuma​

Hareketler bankadan değil, ödemehub'ın sakladığı kayıtlardan döner:

  • ödemehub her hesabı saatte bir bankadan okur; yanıttaki hareketler bankanın en fazla yaklaşık bir saat gerisindedir.
  • Hesap eklendiğinde son 7 günün hareketleri okunur. Daha eski hareketler gelmez.
  • Aynı hareket her sorguda aynı token'la döner. Hareketleri kendi sisteminizde token'la eşleştirin.
  • amount işaretlidir: hesaba giren para artı, çıkan para eksi ("-40.00").
  • created_from ve created_to, bankanın hareketi kaydettiği gündür (booked_at), çalışma alanınızın saat diliminde; ödemehub'ın okuduğu an değil.

Hesabın son okuması retrieve-bank-accounts yanıtında görünür: synced_at null ise hesap henüz okunmadı; last_error doluysa son okuma başarısız oldu ve alan bankanın mesajını taşır. Okuma başarısız olmaya başladığında çalışma alanının Yönetici ve Yetkili üyelerine e-posta gider. Çoğu zaman kimlik bilgilerinin süresi dolmuştur; yenilerini update-bank-account ile gönderin.

Yanıt her zaman sayfalıdır; page ve per_page gönderilmezse ilk 250 hareket döner. Yanıttaki pagination.page, pagination.last_page'e ulaşana kadar page'i artırarak sorarsınız:

use Gurmehub\Odemehub\Request\RetrieveBankTransactions;

$page = 1;

do {
$list = $client->retrieveBankTransactions(new RetrieveBankTransactions(
bankAccountTokens: [$bankAccountToken],
createdFrom: '2026-10-20',
createdTo: '2026-10-26',
page: $page++,
));

foreach ($list->bankTransactions as $bankTransaction) {
$bankTransaction->token;
$bankTransaction->amount; // "22164.96" giren, "-40.00" çıkan
}
} while ($list->pagination->hasMorePages());

Birden çok hesabın token'ını birlikte gönderebilirsiniz (en fazla 50); hareketler bankanın kayıt anına göre iç içe, eskiden yeniye sıralanır ve her hareket bank_account_token taşır.

Hesabı değiştirme ve silme​

  • update-bank-account hesabın adını ya da kimlik bilgilerini değiştirir. Yeni kimlik bilgileri önce bankada denenir; banka reddederse result.successful false döner ve hiçbir şey değişmez. Banka ve IBAN değişmez; başka bir IBAN başka bir hesaptır.
  • delete-bank-account hesabı ve ondan okunan bütün hareketleri siler.

Banka hareketleri için webhook gönderilmez; yeni hareketleri retrieve-bank-transactions ile sorarsınız.

Uçlar​

Uçİşlem
retrieve-banksEklenebilen bankaları ve istedikleri kimlik bilgisi alanlarını listeler.
create-bank-accountBağlantıyı bankada dener, başarılıysa hesabı ekler.
retrieve-bank-accountsHesapları token'larıyla ya da hepsini listeler.
update-bank-accountHesabın adını ya da kimlik bilgilerini değiştirir.
delete-bank-accountHesabı ve hareketlerini siler.
retrieve-bank-transactionsHareketleri hesap token'larıyla, en fazla 7 günlük aralıkta, sayfa sayfa listeler.

Banka hesabı ve hareket nesnelerinin alanları: Banka hesabı nesnesi, Hareket nesnesi.