Writing a Payment Gateway

checkout snapshot   core writes a `checkouts` row holding the exact figures the client saw
      |
pay surface         MODULE  payment_screen() decides what the client meets
      |
capture / callback  MODULE  capture($params) charges, or callback() receives the provider's return
      |
settle              core    settle_checkout() books the payment onto the invoices

Acme.php        the class: extends PaymentGatewayModule
config.php      returns ['meta' => [...], 'settings' => [...]]
lang/en.php     returns a flat key => string map, read as $this->lang['key']
lang/tr.php
logo.png        shown in the admin module list and on the checkout method row

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

        // $this->links['callback'] is now the public return address for this
        // module, signed with get_auth_token(); hand it to the provider.
    }
}

<?php
return [
    'meta' => [
        'name'                   => 'Acme Pay',
        'version'                => '1.0',
        'icon_type'              => 'font',
        'icon'                   => 'bi bi-credit-card',
        'card-storage-supported' => false,  // can vault a card token
        'auto-payment-supported' => false,  // can charge off session (auto pay)
        'standard-card-form'     => false,  // renders the shared card entry form
        'embedded-pane'          => true,   // pane may embed inside the checkout page
        'subscription-mode'      => 'amount',  // items | amount | fixed, see below
        'subscription-anchor'    => false,  // may start an agreement on a future date
    ],
    'settings' => [
        'commission_rate'      => 0,
        'force_convert_to'     => 0,
        'min_amount'           => 0,   // accepted amount range; 0 leaves the bound off
        'max_amount'           => 0,
        'amount_limit_cid'     => 0,   // currency the two bounds are written in
        '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'] ?? '',
        ],
    ];
}

// The checkout in play
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;      // authoritative amount to charge
public function checkout_currency(): int;     // currency id, NOT the ISO code
public function getItems(): array;

// Currency
public function cid_convert_code($id = 0);    // 4 => "USD"
public function currency($id = 0);            // idempotent: id or code in, row out

// Money and fees
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;

// Cards
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;

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

// Plumbing
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);

// The three the core calls, overridable
public function payment_screen(): array;
public function pre_area(): string|false;
public function pre_capture(): string;

// The settlement, called for you. Never call it from module code.
public static function settle_checkout(PaymentGatewayModule $module, array $checkout, array $result): array;

public function capture($params = []);                 // card charge, returns the status array
public function area($params = []);                    // redirect gateway, returns markup
public function callback();                            // provider return, returns the status array
public function bin_check($number);                    // local BIN table, returns card metadata
public function config_fields();                       // admin settings fields
public function refundInvoice($invoice = []);          // refund, returns bool
public function card_setup_result(): array;            // OVERRIDE: 3-D return of a vaulting run

// The sandboxes declare one parameter, but the core calls this with TWO: the
// charge base is passed so a provider whose plans depend on the amount can ask.
public function installment_rates($bin = [], $base = 0);   // [count => deferred-interest percent]

// Subscriptions
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' mode: drop one line

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

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

        // The return address the provider will call. The auth token inside
        // $this->links['callback'] is what makes the dispatcher accept it, and
        // custom_id is how the callback finds this checkout without a session.
        $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 code, already converted
            'reference'   => 'chk_' . (int) $this->checkout_id,
            'return_url'  => $return,
        ]);

        if (($session['url'] ?? '') === '')
            return '';   // an empty return makes payment_screen() report mode "error"

        $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() populates $this->checkout, $this->checkout_id and the
    // client info, so checkout_total() and checkout_currency() answer below.
    $this->set_checkout($checkout);

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

    // Verify BEFORE trusting anything: the callback address is public.
    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],

        // Report what was ACTUALLY taken when it differs from the snapshot,
        // for example after an installment plan chosen on the provider page.
        'paid'        => [
            'amount'   => (float) ($remote['amount'] ?? $this->checkout_total()),
            'currency' => $this->checkout_currency(),
        ],
    ];
}

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

// 1. already paid?          -> short circuit, no second booking
// 2. status not successful  -> log, send the client to links['failed']
// 3. deferred order?        -> build the order and the invoice from the blueprint
// 4. charged more than the snapshot? -> book the installment surcharge first
// 5. book each invoice:
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,                 // from message['Transaction ID']
        'description'    => $module->lang["name"] ?? $module->name,
    ]);
}