Ödeme Kuruluşu Kancaları

1.6k görüntülenme Markdown

Ödeme kuruluşuyla konuşan on dört kanca: uzlaşma, geri dönüş bildirimi, saklı kartlar ve abonelik tahsilatı.

Genel Bakış

Ödeme kuruluşuyla iletişim iki yönlüdür. Biz bir tahsilat isteriz, kuruluş cevabını ya hemen verir ya da sonradan geri bildirim olarak gönderir. İkinci yol tarayıcıdan da gelebilir, doğrudan sunucudan da.

Saklı kartlarda ise kart numarası bize hiç gelmez: kuruluş bir anahtar saklar, biz yalnız gösterim bilgisini (son dört hane, marka, son kullanma) tutarız. Kancalara da yalnız o bilgi gelir.

Referans

Uzlaşmayı izleme

actionpayment.settled
PaymentGatewayModule beklemede olabilir

Ödeme kuruluşuyla uzlaşma tamamlandıktan sonra çalışır.

Parametreler 4
$modulePaymentGatewayModuleUzlaşmayı yapan modül örneği.
$checkoutarrayÖdeme kaydının yazım sonrası hâli: durumu ödenmiş, içinde uzlaşma zamanı ve işlem numarası. settled_status alanı pending olabilir: para henüz kesinleşmemiş demektir.
$resultarrayModülün ham sonucu: durum, mesaj, ödendi işareti, abonelik bilgisi. Kuruluşun kendi diliyle konuşur.
$responsearrayÇekirdeğe dönecek cevap: durum, beklemede işareti, yönlendirme adresi.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.settled', 10,
    function ($module, $checkout, $result, $response) {
        // BEKLEMEDE olabilir: para kesinlesmeden hizmet acmayin.
        if (($checkout['data']['settled_status'] ?? '') !== 'successful') return;

        Accounting::gatewaySettled($module->name, $checkout);
    });

Geri bildirimi izleme

actionpayment.callback_returned
PaymentGatewayModule kayıt boş olabilir

Ödeme kuruluşunun geri bildirimi yorumlandıktan sonra çalışır.

Parametreler 4
$modulePaymentGatewayModuleBildirimi yorumlayan modül.
$checkoutarrayÖdeme kaydı. Modül kaydı çözemediyse boş dizi gelir: sahte ya da eşleşmeyen bir bildirim olabilir.
$settlearrayUzlaşma sonucu: durum, yönlendirme, mesaj ve already işareti. already "bu bildirim daha önce işlendi" demektir.
$is_s2sboolBildirim doğrudan sunucudan mı geldi. false ise müşterinin tarayıcısı döndürmüştür; müşteri o sayfayı hiç açmamış da olabilir.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.callback_returned', 10,
    function ($module, $checkout, $settle, $is_s2s) {
        // Bos checkout = eslesmeyen bildirim; tekrar isaretini de kontrol edin.
        if (!$checkout || !empty($settle['already'])) return;

        Ops::note('gateway-callback', $module->name, $is_s2s ? 'sunucu' : 'tarayici');
    });

Kart eklemeyi durdurma

gatepayment.card_add
AccountCards numara gelmez

Müşteri kart eklerken çalışır. Kart numarası bu kancaya gelmez; karar için yalnız hesap ve modül bilgisi vardır.

Parametreler 3
$uidintKartı ekleyen hesap. Kendi hesabı olduğu doğrulanmıştır.
$moduleNamestringKart saklayan ödeme kuruluşu modülü.
$autoPayboolKart otomatik ödeme zincirine girecek mi. Modül desteklemiyorsa hep false.
Dönüş 1
stringBoş olmayan bir string kart eklemeyi durdurur.
Dinleyici 
Hook::add('gate:payment.card_add', 10, function ($uid, $moduleName, $autoPay) {
    // Kart numarasi buraya GELMEZ: karari hesap uzerinden verin.
    if (Acme::cardCount($uid) >= 5) return 'En fazla 5 kart saklanir.';

    return null;
});

Kart saklandığını izleme

actionpayment.card_stored
AccountCards yalnız gösterim bilgisi

Kart kuruluşta saklandıktan sonra çalışır.

Parametreler 4
$userIdintKartın sahibi.
$cardIdintSaklanan kart kaydının kimliği.
$modulestringKartı saklayan modül.
$cardarrayYalnız gösterim bilgisi: son dört hane, marka, tip, son kullanma ayı ve yılı. Kart numarası, güvenlik kodu ve kuruluş anahtarı burada yoktur ve olmayacaktır.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.card_stored', 10, function ($userId, $cardId, $module, $card) {
    // Yalniz gosterim bilgisi gelir; numara ve token asla.
    Notify::securityEvent($userId, 'card-added', $card['ln4'] ?? '');
});

Varsayılan kartı izleme

actionpayment.card_default_set
AccountCards otomatik ödeme buradan

Bir kart varsayılan yapıldıktan sonra çalışır.

Parametreler 2
$uidintKartın sahibi.
$cardIdintVarsayılan yapılan kartın kimliği. Otomatik ödeme bundan sonra bu kartı dener.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.card_default_set', 10, function ($uid, $cardId) {
    Audit::note('card-default', (string) $uid, (string) $cardId);
});

Kart silmeyi izleme

actionpayment.card_removed
AccountCards otomatik ödeme etkilenir

Saklı kart silindikten sonra çalışır.

Parametreler 2
$uidintKartın sahibi.
$cardIdintSilinen kartın kimliği.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.card_removed', 10, function ($uid, $cardId) {
    // Son kart silindiyse otomatik odeme sessizce durur: musteriyi uyarin.
    if (Acme::cardCount($uid) === 0) Notify::noCardLeft($uid);
});

Abonelik iptalini durdurma

gatepayment.subscription_cancel
AccountCards kuruluştaki anlaşma

Müşteri ödeme kuruluşundaki tekrarlayan anlaşmayı iptal ederken çalışır.

Parametreler 2
$uidintAnlaşmanın sahibi.
$idintİptal edilecek anlaşmanın kimliği.
Dönüş 1
stringBoş olmayan bir string iptali durdurur.
Dinleyici 
Hook::add('gate:payment.subscription_cancel', 10, function ($uid, $id) {
    // Anlasma iptali hizmeti kapatmaz ama odemeyi keser: once uyarin.
    if (Acme::activeServices($uid) > 0 && !Acme::confirmed($uid))
        return 'Aktif hizmetiniz var; iptali onaylamaniz gerekiyor.';

    return null;
});

Abonelik yoklamasını izleme

actionpayment.subscription_polled
cronjobs/SubscriptionPoll düzenli çalışır

Zamanlanmış görev ödeme kuruluşundaki anlaşmaları sorguladıktan sonra çalışır.

Parametreler 2
$subscriptionarrayYoklanan anlaşma kaydı.
$resultarrayKuruluştan dönen sonuç. Yoklama düzenli çalışır: aynı anlaşma için defalarca gelir.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.subscription_polled', 10, function ($subscription, $result) {
    // Duzenli calisir: her yoklamada degil, DEGISIKLIKTE tepki verin.
    Acme::syncSubscription($subscription, $result);
});

Kuruluş ayarlarının kaydını izleme

actionpayment.settings_saved
PaymentGatewayModule diske yazıldıktan sonra

Bir ödeme modülünün ayarları kaydedildikten sonra çalışır.

Parametreler 2
$module_namestringAyarları kaydedilen modülün adı.
$configarrayDiske yazılan yapılandırmanın tamamı. İçinde API anahtarı ve gizli değerler bulunur: kendi kaydınıza ya da günlüğünüze yazmayın.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.settings_saved', 10, function ($module_name, $config) {
    // Yapilandirmanin kendisini DEGIL, yalniz degistigi bilgisini tasiyin.
    Acme::notifyOps('odeme ayari degisti: ' . $module_name);
});

Kart sorgusunu devralma

filterpayment.bin_lookup
Payment bağla geçer

Kartın ilk hanelerinden banka ve tip çözülürken çalışır. Doldurursanız dış servise hiç gidilmez.

Parametreler 2
$resultarray|falsebağlaSorgu sonucu. Beklenen alanlar: ülke, kart tipi, şema, banka adı ve marka.
$bin_numberstringKartın ilk altı hanesi.
Dönüş 1
voidDönüş yoksayılır; sonucun üzerine yazarsınız. Dokunmazsanız dış sorgu normal biçimde sürer. Kendi önbelleğinizi buraya bağlamak, her ödemede dışarı çıkmayı önler.
Dinleyici 
Hook::add('filter:payment.bin_lookup', 10, function (&$result, $bin_number) {
    // Kendi onbelleginiz varsa dis servise hic cikmayin.
    $cached = Acme::binCache($bin_number);
    if ($cached) $result = $cached;
});

Ödeme panelini kendi ekranınızla değiştirme

filterpayment.gateway_pane
Checkout bağla geçer

Ödeme adımında kuruluşun paneli hazırlanırken çalışır. Kendi ekranınızı burada gösterir, klasik ödeme sayfasını atlarsınız.

Parametreler 2
$htmlstringbağlaPanelde görünecek içerik.
$ctxarraybağlaBağlam.
Dönüş 1
voidDönüş yoksayılır. İçeriği dolu bırakırsanız sizin ekranınız gösterilir; boş bırakırsanız klasik ödeme sayfasına düşülür. Yani boşaltmak da bir karardır.
Dinleyici 
Hook::add('filter:payment.gateway_pane', 10, function (&$html, &$ctx) {
    // Dolu birakmak kendi ekraniniz, bos birakmak klasik sayfa demektir.
    $html = Acme::renderPane($ctx);
});

Anlaşmanın iptalini izleme

actionpayment.subscription_cancelled
AccountSubscriptions iptal sonrası

Bir ödeme anlaşması iptal edildikten sonra çalışır. Bundan sonra o anlaşmadan tahsilat gelmez.

Parametreler 2
$subscription_idintİptal edilen anlaşmanın kimliği.
$subarrayAnlaşma satırının iptal öncesi hâli: sahibi, modülü, tanımlayıcısı, para birimi ve dönemi.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.subscription_cancelled', 10, function ($subscription_id, $sub) {
    // Bagli hizmetler artik otomatik tahsilatsiz kalir.
    Acme::warnUnpaidRisk((int) ($sub['user_id'] ?? 0));
});

Anlaşmadan üye çıkarmayı durdurma

gatepayment.subscription_member_remove
AccountSubscriptions çıkarmadan önce

Bir hizmet ya da eklenti ödeme anlaşmasından çıkarılmadan önce çalışır.

Parametreler 6
$uidintAnlaşmanın sahibi.
$subscription_idintAnlaşmanın kimliği.
$typestringservice ya da addon.
$midintÜyenin kimliği.
$memberarrayÇıkarılacak üye satırı. Eklentide sahip alanı üst hizmetin kimliğini taşır, kullanıcınınkini değil: buna göre okuyun.
$subarrayAnlaşma satırı.
Dönüş 1
string|nullBoş olmayan bir metin çıkarmayı engeller ve hata olarak gösterilir. Boş dönüş devam ettirir.
Dinleyici 
Hook::add('gate:payment.subscription_member_remove', 10,
    function ($uid, $subscription_id, $type, $mid, $member, $sub) {
        // Taahhut suresi dolmadan cikarmaya izin vermeyin.
        if (Acme::underCommitment($mid, $type)) return 'Taahhut suresi dolmadan cikarilamaz.';

        return null;
    });

Üyenin çıkarılmasını izleme

actionpayment.subscription_member_removed
AccountSubscriptions çıkarma sonrası

Üye anlaşmadan çıkarıldıktan sonra çalışır.

Parametreler 5
$typestringservice ya da addon.
$idintÜyenin kimliği.
$memberarrayÜye satırının çıkarma öncesi hâli. Anlaşma alanı hâlâ eski değeri taşır: “hangi anlaşmadan çıktı” sorusunun cevabı buradadır.
$subarrayAnlaşma satırının değişim öncesi hâli; durumu ve tutarı eski değerleridir.
$historyarrayİşlemin sonucu, geçmiş kaydına yazılanla aynı.
Dönüş 1
voidDönüş yoksayılır.
Dinleyici 
Hook::add('action:payment.subscription_member_removed', 10,
    function ($type, $id, $member, $sub, $history) {
        // 'Hangi anlasmadan cikti' sorusu eski degerde durur.
        Acme::detached($type, $id, (int) ($member['subscription_id'] ?? 0));
    });

Tuzaklar

Uzlaşma "para geldi" demek değildir

Uzlaşma kaydında durum beklemede olabilir: kuruluş işlemi almış ama kesinleştirmemiştir. Bu durumu kontrol etmeden hizmet açan bir dinleyici, sonradan başarısız olan bir ödeme için bedava hizmet vermiş olur.

Geri bildirimde kayıt boş olabilir

Modül bildirimi bir ödeme kaydına bağlayamazsa kanca boş bir dizi alır. Bu, sahte ya da eşleşmeyen bir bildirim demektir. Ayrıca aynı bildirim tekrar gelebilir; sonuçtaki "daha önce işlendi" işaretini kontrol etmeyen dinleyici işi çiftler.

Kart numarası hiçbir kancaya gelmez

Saklı kart kancaları yalnız gösterim bilgisi taşır: son dört hane, marka, son kullanma. Numara, güvenlik kodu ve kuruluş anahtarı bize hiç gelmez. Kart üzerinden karar veren bir kural yazamazsınız; kararınızı hesap üzerinden kurun.

Tarayıcı dönüşü güvenilir bir sinyal değildir

Geri bildirim sunucudan gelmişse ödeme kuruluşu konuşuyordur. Tarayıcıdan geldiyse müşteri o sayfayı hiç açmamış olabilir — kapatmış, ağı kopmuş, yönlendirmeyi kaçırmış olabilir. Paraya bağlı işi sunucu bildirimine dayandırın.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası