Ödeme Geçidi Yazma

anlık görüntü       core, müşterinin gördüğü tam rakamları taşıyan bir `checkouts` satırı yazar
      |
ödeme yüzeyi        MODULE  payment_screen() müşterinin neyle karşılaşacağına karar verir
      |
capture / callback  MODULE  capture($params) çeker ya da callback() sağlayıcının dönüşünü alır
      |
settle              core    settle_checkout() ödemeyi faturalara işler

Acme.php        sınıf: extends PaymentGatewayModule
config.php      ['meta' => [...], 'settings' => [...]] döndürür
lang/en.php     düz bir key => string haritası döndürür, $this->lang['key'] ile okunur
lang/tr.php
logo.png        admin modül listesinde ve ödeme yöntemi satırında görünür

class Acme extends PaymentGatewayModule
{
    public function __construct()
    {
        parent::__construct();

        // $this->links['callback'] artık bu modülün herkese açık dönüş adresidir,
        // get_auth_token() ile imzalanmıştır; onu sağlayıcıya verin.
    }
}

<?php
return [
    'meta' => [
        'name'                   => 'Acme Pay',
        'version'                => '1.0',
        'icon_type'              => 'font',
        'icon'                   => 'bi bi-credit-card',
        'card-storage-supported' => false,  // kart jetonunu kasaya alabilir
        'auto-payment-supported' => false,  // oturum dışı çekim yapabilir (otomatik ödeme)
        'standard-card-form'     => false,  // ortak kart giriş formunu basar
        'embedded-pane'          => true,   // panel ödeme sayfasının içine gömülebilir
        'subscription-mode'      => 'amount',  // items | amount | fixed, aşağıya bakın
        'subscription-anchor'    => false,  // ileri bir tarihte sözleşme başlatabilir
    ],
    'settings' => [
        'commission_rate'      => 0,
        'force_convert_to'     => 0,
        'min_amount'           => 0,   // kabul edilen tutar aralığı; 0 sınırı kapatır
        'max_amount'           => 0,
        'amount_limit_cid'     => 0,   // iki sınırın yazıldığı para birimi
        'accepted_countries'   => [],
        'unaccepted_countries' => [],
    ],
];

public function config_fields()
{
    return [
        'merchant_id' => [
            'name'        => $this->lang['merchant-id'] ?? 'Merchant ID',
            'description' => $this->lang['merchant-id-desc'] ?? '',
            'type'        => 'text',
            'value'       => $this->config['settings']['merchant_id'] ?? '',
            'placeholder' => 'acme_12345',
        ],
        'secret_key' => [
            'name'  => $this->lang['secret-key'] ?? 'Secret Key',
            'type'  => 'password',
            'value' => $this->config['settings']['secret_key'] ?? '',
        ],
    ];
}

// İşlemdeki checkout
public function set_checkout($checkout): void;
public function get_checkout($id = 0, $status = '', $type = '', $uid = 0);
public function save_checkout($id = 0, $fields = []): bool;
public function checkout_total(): float;      // çekilecek tek doğru tutar
public function checkout_currency(): int;     // para birimi id'si, ISO kodu DEĞİL
public function getItems(): array;

// Para birimi
public function cid_convert_code($id = 0);    // 4 => "USD"
public function currency($id = 0);            // idempotent: girdi id ya da kod, çıktı satır

// Para ve ücretler
public function commission_fee_calculator($amount): float;
public function get_commission_rate();
public function installment_plans(array $bin, float $base, int $cid): array;
public function installment_plan_total(float $base, float $rate): float;

// Kartlar
public function get_stored_card($id = 0, $user_id = 0): array;
public function checkSaveCard(): bool;
public function checkAutoPay(): bool;
public function card_setup_result(): array;
public function generate_card_identification_checkout($pmethod = ''): int;

// Abonelikler
public function checkout_subscribable(): array;
public function set_subscribed_items($arg = []): void;
public function set_subscribed_sources(array $sources = []): void;

// Altyapı
public function get_auth_token(): string;
public function define_function($name = '', $function_name = ''): void;
public function controller_settings($extraFields = []): array;
public function isEnabled(): bool;
public function save_custom_data($data, $checkout_id = 0): void;
public function get_custom_data($checkout_id = 0);

// Çekirdeğin çağırdığı üçlü, ezilebilir
public function payment_screen(): array;
public function pre_area(): string|false;
public function pre_capture(): string;

// Mahsup, sizin için çağrılır. Modül kodundan asla çağırmayın.
public static function settle_checkout(PaymentGatewayModule $module, array $checkout, array $result): array;

public function capture($params = []);                 // kart çekimi, durum dizisi döner
public function area($params = []);                    // yönlendirme geçidi, işaretleme döner
public function callback();                            // sağlayıcı dönüşü, durum dizisi döner
public function bin_check($number);                    // yerel BIN tablosu, kart üst verisi döner
public function config_fields();                       // yönetici ayar alanları
public function refundInvoice($invoice = []);          // iade, bool döner
public function card_setup_result(): array;            // EZME: kasaya alma koşusunun 3-D dönüşü

// Sanal test modülleri tek parametre bildirir, ama çekirdek bunu İKİ parametreyle
// çağırır: planları tutara bağlı olan bir sağlayıcı sorabilsin diye çekim tabanı da geçilir.
public function installment_rates($bin = [], $base = 0);   // [adet => vade farkı yüzdesi]

// Abonelikler
public function cancel_subscription($params = []): bool;
public function get_subscription($params = []): array|false;
public function change_subscription_fee($params = [], $value = 0, $currency = 0): bool;
public function remove_subscription_item($params = []): bool;   // 'items' modu: tek satırı düşür

$base = $this->checkout_total();
$fee  = $this->commission_fee_calculator($base);   // oran config['settings']['commission_rate']'ten okunur
$note = Money::formatter_symbol($fee, $this->checkout_currency());

class Acme extends PaymentGatewayModule
{
    public function area($params = [])
    {
        $cid = (int) ($params['currency_id'] ?? 0);

        // Sağlayıcının çağıracağı dönüş adresi. Dağıtıcının onu kabul etmesini
        // $this->links['callback'] içindeki kimlik jetonu sağlar; custom_id ise
        // geri dönüşün bu checkout'u oturumsuz bulma yoludur.
        $return = LinkGenerator::wQS($this->links['callback'], [
            'custom_id' => (int) ($params['checkout_id'] ?? $this->checkout_id),
        ]);

        $session = $this->open_provider_session([
            'merchant'    => $this->config['settings']['merchant_id'] ?? '',
            'amount'      => $params['amount'] ?? 0,
            'currency'    => $params['currency'] ?? '',   // ISO kodu, çevrilmiş hâlde
            'reference'   => 'chk_' . (int) $this->checkout_id,
            'return_url'  => $return,
        ]);

        if (($session['url'] ?? '') === '')
            return '';   // boş bir dönüş, payment_screen()'in "error" modu bildirmesine yol açar

        $label  = htmlspecialchars((string) ($this->lang['pay-button'] ?? 'Continue'), ENT_QUOTES);
        $target = htmlspecialchars($session['url'], ENT_QUOTES);
        $amount = htmlspecialchars(Money::formatter_symbol((float) ($params['amount'] ?? 0), $cid), ENT_QUOTES);

        return '<div class="d-grid">'
            . '<span class="price-chip num-tabular mb-2">' . $amount . '</span>'
            . '<a class="btn btn-primary btn-lg" href="' . $target . '">' . $label . '</a>'
            . '</div>';
    }
}

public function callback()
{
    $checkout_id = (int) Filter::init("REQUEST/custom_id", "numbers");
    $checkout    = $checkout_id ? $this->get_checkout($checkout_id) : false;

    if (!$checkout)
        return ['status' => "error", 'message' => "checkout-not-found"];

    // set_checkout(), $this->checkout, $this->checkout_id ve müşteri bilgisini
    // doldurur; böylece checkout_total() ve checkout_currency() aşağıda yanıt verir.
    $this->set_checkout($checkout);

    $reference = (string) Filter::init("REQUEST/reference", "letters_numbers");
    $signature = (string) Filter::init("REQUEST/signature", "letters_numbers");

    // Hiçbir şeye güvenmeden ÖNCE doğrulayın: geri dönüş adresi herkese açıktır.
    if (!$this->signature_matches($reference, $signature))
        return ['status' => "error", 'checkout_id' => $checkout_id, 'message' => $this->pay_lang("error-verification")];

    $remote = $this->fetch_provider_charge($reference);

    if (($remote['state'] ?? '') !== 'captured')
        return [
            'status'      => "error",
            'checkout_id' => $checkout_id,
            'message'     => (string) ($remote['reason'] ?? ($this->lang['error-declined'] ?? 'Declined.')),
        ];

    return [
        'status'      => "successful",
        'checkout_id' => $checkout_id,
        'message'     => ['Transaction ID' => $reference],

        // Anlık görüntüden farklıysa GERÇEKTEN çekilen tutarı bildirin, örneğin
        // sağlayıcının sayfasında bir taksit planı seçildikten sonra.
        'paid'        => [
            'amount'   => (float) ($remote['amount'] ?? $this->checkout_total()),
            'currency' => $this->checkout_currency(),
        ],
    ];
}

// coremio/classes/PaymentGatewayModule.php, settle_checkout()
$result = $module->callback();

// 1. zaten ödendi mi?          -> kısa devre, ikinci kayıt yok
// 2. durum successful değil    -> logla, müşteriyi links['failed']'a gönder
// 3. ertelenmiş sipariş mi?    -> siparişi ve faturayı şablondan kur
// 4. anlık görüntüden fazlası mı çekildi? -> önce taksit vade farkını kaydet
// 5. her faturayı kaydet:
foreach (\Checkout::invoice_ids($fresh) as $invoiceId) {
    $due = round((float) Invoices::balance($invoiceId), 2);
    if ($due <= 0.005) continue;

    Invoices::add_payment($invoiceId, [
        'amount'         => $due,
        'currency'       => (int) (Invoices::get($invoiceId, ['select' => "currency"])["currency"] ?? 0),
        'pmethod'        => $module->name,
        'transaction_id' => $tx,                 // message['Transaction ID']'den gelir
        'description'    => $module->lang["name"] ?? $module->name,
    ]);
}