Payment Methodمن الصفر.

<config>
  <default>
    <payment>
      <mygateway>
        <!-- الكلاس اللي بيمثّل الطريقة -->
        <model>MyGatewayFacade</model>
        <active>0</active>
        <title>Pay by Card</title>

        <!-- authorize أو authorize_capture -->
        <payment_action>authorize</payment_action>

        <!-- الدول المسموحة -->
        <allowspecific>0</allowspecific>

        <!-- حدود المبلغ -->
        <min_order_total>0</min_order_total>
        <max_order_total>10000</max_order_total>

        <!-- العملات المدعومة -->
        <currency>SAR,AED,EGP</currency>
      </mygateway>
    </payment>
  </default>
</config>

<group id="mygateway" translate="label"
  sortOrder="10" showInDefault="1" showInWebsite="1">
  <label>My Gateway</label>

  <field id="active" type="select" sortOrder="10"
    showInDefault="1" showInWebsite="1">
    <label>Enabled</label>
    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
  </field>

  <!-- المفتاح السري — لاحظ backend_model -->
  <field id="secret_key" type="obscure" sortOrder="30"
    showInDefault="1" showInWebsite="1">
    <label>Secret Key</label>
    <backend_model>
      Magento\Config\Model\Config\Backend\Encrypted
    </backend_model>
  </field>
</group>

<!-- الكلاس اللي Magento بيتعامل معاه -->
<virtualType name="MyGatewayFacade"
  type="Magento\Payment\Model\Method\Adapter">
  <arguments>
    <argument name="code" xsi:type="const">
      Vendor\Payment\Model\Ui\ConfigProvider::CODE
    </argument>

    <!-- الواجهة في الـ checkout -->
    <argument name="formBlockType" xsi:type="string">
      Magento\Payment\Block\Form
    </argument>

    <!-- إيه اللي الطريقة دي تقدر تعمله -->
    <argument name="valueHandlerPool" xsi:type="object">
      MyGatewayValueHandlerPool
    </argument>

    <!-- العمليات المتاحة -->
    <argument name="commandPool" xsi:type="object">
      MyGatewayCommandPool
    </argument>
  </arguments>
</virtualType>

<virtualType name="MyGatewayCommandPool"
  type="Magento\Payment\Gateway\Command\CommandPool">
  <arguments>
    <argument name="commands" xsi:type="array">
      <item name="authorize" xsi:type="string">
        MyGatewayAuthorizeCommand
      </item>
      <item name="capture" xsi:type="string">
        MyGatewayCaptureCommand
      </item>
      <item name="refund" xsi:type="string">
        MyGatewayRefundCommand
      </item>
      <item name="void" xsi:type="string">
        MyGatewayVoidCommand
      </item>
    </argument>
  </arguments>
</virtualType>

<virtualType name="MyGatewayAuthorizeCommand"
  type="Magento\Payment\Gateway\Command\GatewayCommand">
  <arguments>
    <!-- تجهيز الطلب -->
    <argument name="requestBuilder" xsi:type="object">
      MyGatewayAuthorizeRequest
    </argument>

    <!-- إرساله -->
    <argument name="transferFactory" xsi:type="object">
      Vendor\Payment\Gateway\Http\TransferFactory
    </argument>
    <argument name="client" xsi:type="object">
      Vendor\Payment\Gateway\Http\Client
    </argument>

    <!-- التحقق ومعالجة الرد -->
    <argument name="validator" xsi:type="object">
      Vendor\Payment\Gateway\Validator\ResponseValidator
    </argument>
    <argument name="handler" xsi:type="object">
      MyGatewayResponseHandlerComposite
    </argument>
  </arguments>
</virtualType>

namespace Vendor\Payment\Gateway\Request;

use Magento\Payment\Gateway\Request\BuilderInterface;
use Magento\Payment\Gateway\Helper\SubjectReader;

class AuthorizeBuilder implements BuilderInterface
{
    public function build(array $buildSubject): array
    {
        // استخراج بيانات الدفع بالطريقة الصحيحة
        $paymentDO = SubjectReader::readPayment($buildSubject);
        $amount    = SubjectReader::readAmount($buildSubject);

        $payment = $paymentDO->getPayment();
        $order   = $paymentDO->getOrder();

        return [
            // التوكن من الواجهة — مش بيانات كارت
            'payment_token' => $payment->getAdditionalInformation(
                'payment_token'
            ),

            // المبلغ بالعملة الأساسية
            'amount'   => $this->formatAmount($amount),
            'currency' => $order->getCurrencyCode(),

            // مرجع فريد للمعاملة
            'reference' => $order->getOrderIncrementId(),

            'capture' => false,  // تفويض بس
        ];
    }

    // كتير من البوابات بتستقبل المبلغ بالوحدة الصغرى
    private function formatAmount(float $amount): int
    {
        return (int) round($amount * 100);
    }
}

namespace Vendor\Payment\Gateway\Response;

use Magento\Payment\Gateway\Response\HandlerInterface;
use Magento\Payment\Gateway\Helper\SubjectReader;

class TxnIdHandler implements HandlerInterface
{
    public function handle(
        array $handlingSubject,
        array $response
    ): void {
        $paymentDO = SubjectReader::readPayment(
            $handlingSubject
        );
        $payment = $paymentDO->getPayment();

        // مرجع المعاملة عند البوابة — مهم جداً
        $payment->setTransactionId($response['transaction_id']);

        // المعاملة مش مقفولة — لسه فيه capture
        $payment->setIsTransactionClosed(false);

        // نحتفظ بالمرجع للعمليات الجاية
        $payment->setAdditionalInformation(
            'gateway_reference',
            $response['reference']
        );
    }
}

class ResponseValidator extends AbstractValidator
{
    public function validate(array $validationSubject): ResultInterface
    {
        $response = SubjectReader::readResponse(
            $validationSubject
        );

        $isValid = isset($response['status'])
            && $response['status'] === 'approved';

        if ($isValid) {
            return $this->createResult(true);
        }

        // رسالة عامة للعميل — مش تفاصيل البوابة
        return $this->createResult(false, [
            __('Payment could not be processed.')
        ]);
    }
}

namespace Vendor\Payment\Model\Ui;

use Magento\Checkout\Model\ConfigProviderInterface;

class ConfigProvider implements ConfigProviderInterface
{
    public const CODE = 'mygateway';

    public function __construct(
        private readonly Config $config
    ) {}

    public function getConfig(): array
    {
        return [
            'payment' => [
                self::CODE => [
                    // المفتاح العام فقط — مش السري
                    'publicKey' => $this->config->getPublicKey(),
                    'sandbox'   => $this->config->isSandbox(),
                ],
            ],
        ];
    }
}

class Index extends Action implements CsrfAwareActionInterface
{
    // الـ webhook مالهوش form key
    public function validateForCsrf(RequestInterface $r): ?bool
    {
        return true;
    }

    public function createCsrfValidationException(
        RequestInterface $request
    ): ?InvalidRequestException {
        return null;
    }

    public function execute()
    {
        $payload   = $this->getRequest()->getContent();
        $signature = $this->getRequest()
            ->getHeader('X-Gateway-Signature');

        // 1. التحقق من التوقيع — إلزامي
        if (!$this->signatureValidator->isValid(
            $payload, $signature
        )) {
            $this->logger->warning('Invalid webhook signature');
            return $this->respond(401);
        }

        $data = json_decode($payload, true);

        // 2. الحماية من التكرار
        if ($this->log->isProcessed($data['event_id'])) {
            return $this->respond(200);
        }

        try {
            $this->processor->handle($data);
            $this->log->markProcessed($data['event_id']);
        } catch (\Exception $e) {
            $this->logger->error($e->getMessage());
            // 500 عشان البوابة تعيد المحاولة
            return $this->respond(500);
        }

        return $this->respond(200);
    }
}

<!-- Magento بيوفّر آلية جاهزة -->
<virtualType name="MyGatewayLogger"
  type="Magento\Payment\Model\Method\Logger">
  <arguments>
    <argument name="debugReplaceKeys" xsi:type="array">
      <item name="0" xsi:type="string">card_number</item>
      <item name="1" xsi:type="string">cvv</item>
      <item name="2" xsi:type="string">secret_key</item>
    </argument>
  </arguments>
</virtualType>