Laravel’da BayarCash (FPX) Kurulumunu Doğru Şekilde Yapma

Son güncelleme: 4 Temmuz 2026 10:43

Malaysian pazarına SaaS geliştirdiğinizde, bir süre sonra FPX’ye ihtiyacınız olacak ve BayarCash bunlardan biridir. Resmi SDK (webimpian/bayarcash-php-sdk) ihtiyacınızı karşılıyor. Sorun asla SDK değildir; bu, bir kontrolörden doğrudan çağrıldığında, Blade görünümüne durum kodlarını hardcode ettiğinizde ve üretimde BayarCash’in webhook’unuzu 500 döndürdüğünüz için 40 kez yeniden denediğini fark ettiğinizde ortaya çıkar.

<p>Bu, BayarCash’i üç farklı üretim Laravel uygulamasında gönderme sonrasında benim yerleştiğim bir modeldir: etkinlik biletleme, SaaS faturalandırma ile bir destek masası ve bir abonelik ürünü. Aynı ağ geçidi, üç alan adı, her seferinde sağlam bir biçim.</p>

<h2>
    <a name="what-bayarcash-actually-is" href="#what-bayarcash-actually-is">
    </a>
    BayarCash Nedir?
</h2>

<p>Kelimeleri doğru kullanmak önemlidir; entegrasyon hatalarının yarısı bunları karıştırmaktan gelir:</p>

<ul>
    <li>
        <strong>Portal</strong> — bir satıcı seviyesinde ödeme yapılandırması. Bir <code>portal_key</code> alırsınız. Her dağıtım için bir tane.
    </li>
    <li>
        <strong>API token (PAT)</strong> — gelen API çağrılarını doğrular.
    </li>
    <li>
        <strong>Gizli anahtar</strong> — istek yüklerinizi imzalayıp (yani <em>checksum</em>) ve webhook geri çağırmalarını doğrular. Tokenden farklıdır; her ikisini de saklayın.
    </li>
    <li>
        <strong>Ödeme isteği</strong> — bir ödeme POST edersiniz, BayarCash barındırılan bir ödeme <code>url</code>’sı döner, müşteriyi yönlendirirsiniz.
    </li>
    <li>
        <strong>Kanal</strong> — SDK sabitlerini kullanın, asla ham int'ler: <code>Bayarcash::FPX</code> (1), <code>FPX_DIRECT_DEBIT</code> (3), <code>DUITNOW_QR</code> (6).
    </li>
</ul>

<p>Sandbox konsolu: <code>console.bayarcash-sandbox.com</code> → <em>API Ayarları</em>. Canlı paraya dokunmadan önce tüm akışı burada oluşturun.</p>

<h2>
    <a name="install-and-configure" href="#install-and-configure">
    </a>
    Kurulum ve yapılandırma
</h2>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>composer require webimpian/bayarcash-php-sdk

<p>Hesap bilgileri çevrede olmalıdır ve <strong>bir</strong> yerde çözülebilir:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>BAYARCASH_ENV=sandbox

BAYARCASH_API_TOKEN=
BAYARCASH_API_SECRET_KEY=
BAYARCASH_PORTAL_KEY=
BAYARCASH_API_VERSION=v3

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// config/bayarcash.php</span>

return [
‘env’ => env(’BAYARCASH_ENV’, ’sandbox’),
‘token’ => env(’BAYARCASH_API_TOKEN’),
‘secret’ => env(’BAYARCASH_API_SECRET_KEY’),
‘portal_key’ => env(’BAYARCASH_PORTAL_KEY’),
‘api_version’ => env(’BAYARCASH_API_VERSION’, ’v3′),
‘callback_url’=> env(’BAYARCASH_CALLBACK_URL’),
];

<h2>
    <a name="the-one-rule-wrap-dont-replace" href="#the-one-rule-wrap-dont-replace">
    </a>
    Tek kural: sarmak, değiştirmemek
</h2>

<p><strong>Alan kodunuz asla bir BayarCash yükü görmemelidir.</strong> SDK HTTP, imzalama ve yeniden denemeleri yönetir. Göreviniz, alanınız (Siparişler, Abonelikler) ile ağ geçidi arasında tam olarak bir katmanda çeviri yapmaktır. Bu, üç katman oluşturur:</p>

<ol>
    <li>
        <strong>Hafif bir istemci sargısı</strong> — yapılandırmayı bir kez çözer, tipli yöntemleri açar, test mock kesimidir.
    </li>
    <li>
        <strong>Bir ağ geçidi</strong> — bir sözleşme uygular, alanınızı içine ve dışına konuşur.
    </li>
    <li>
        <strong>Bir fabrika/yönetici</strong> — aktif ağ geçidini seçer, böylece BayarCash, Stripe/mock/manual ile değiştirilebilir.
    </li>
</ol>

<h3>
    <a name="layer-1-the-client-wrapper" href="#layer-1-the-client-wrapper">
    </a>
    Katman 1 — istemci sargısı
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="kd">class</span> <span class="nc">BayarCashClient</span>

{
public function __construct(
private readonly Bayarcash $sdk,
private readonly string $secretKey,
private readonly string $portalKey,
) {}

<span class="k">public</span> <span class="k">static</span> <span class="k">function</span> <span class="n">fromConfig</span><span class="p">():</span> <span class="kt">self</span>
<span class="p">{</span>
    <span class="nv">$sdk</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">Bayarcash</span><span class="p">((</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.token'</span><span class="p">));</span>
    <span class="nv">$sdk</span><span class="o">-&gt;</span><span class="nf">setApiVersion</span><span class="p">((</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.api_version'</span><span class="p">,</span> <span class="s1>'v3'</span><span class="p">));</span>

    <span class="k">if</span> <span class="p">(</span><span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.env'</span><span class="p">)</span> <span class="o">===</span> <span class="s1>'sandbox'</span><span class="p">)</span> <span class="p">{</span>
        <span class="nv">$sdk</span><span class="o">-&gt;</span><span class="nf">useSandbox</span><span class="p">();</span>
    <span class="p">}</span>

    <span class="k">return</span> <span class="k">new</span> <span class="nc">self</span><span class="p">(</span><span class="nv">$sdk</span><span class="p">,</span> <span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.secret'</span><span class="p">),</span> <span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.portal_key'</span><span class="p">));</span>
<span class="p">}</span>

<span class="k">public</span> <span class="k">function</span> <span class="n">portalKey</span><span class="p">():</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">portalKey</span><span class="p">;</span> <span class="p">}</span>

<span class="k">public</span> <span class="k">function</span> <span class="n">createPaymentIntent</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$data</span><span class="p">):</span> <span class="kt">object</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">sdk</span><span class="o">-&gt;</span><span class="nf">createPaymentIntent</span><span class="p">(</span><span class="nv">$data</span><span class="p">);</span> <span class="p">}</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">checksum</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$data</span><span class="p">):</span> <span class="kt">string</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">sdk</span><span class="o">-&gt;</span><span class="nf">createPaymentIntentChecksumValue</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="n">secretKey</span><span class="p">,</span> <span class="nv">$data</span><span class="p">);</span> <span class="p">}</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">verifyTransactionCallback</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$c</span><span class="p">):</span> <span class="kt">bool</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">sdk</span><span class="o">-&gt;</span><span class="nf">verifyTransactionCallbackData</span><span class="p">(</span><span class="nv">$c</span><span class="p">,</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">secretKey</span><span class="p">);</span> <span class="p">}</span>

}

<h3>
    <a name="layer-2-a-contract-your-app-speaks" href="#layer-2-a-contract-your-app-speaks">
    </a>
    Katman 2 — uygulamanızın konuştuğu bir sözleşme
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="kd">interface</span> <span class="nc">BillingProvider</span>

{
public function createCheckoutIntent(Workspace $ws, Plan $plan, string $cycle, string $returnUrl): CheckoutIntent;

<span class="cd">/  İmza geçersiz olduğunda null döner — arayıcı 401 ile yanıt verir. */</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">verifyWebhook</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$payload</span><span class="p">):</span> <span class="kt">?WebhookEvent</span><span class="p">;</span>

}

<p>Arayüzün neyi dahil etmediğine dikkat edin: <code>status</code>, <code>portal_key</code>, ağ geçidi alanlarının dizileri yok. Tamamı bu noktada.</p>

<h3>
    <a name="layer-3-bind-it-with-a-fake-fallback" href="#layer-3-bind-it-with-a-fake-fallback">
    </a>
    Katman 3 — bağlayın, bir sahte fallback ile
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nv">$this</span><span class="o">-&gt;</span><span class="n">app</span><span class="o">-&gt;</span><span class="nf">singleton</span><span class="p">(</span><span class="nc">BillingProvider</span><span class="o">::</span><span class="n">class</span><span class="p">,</span> <span class="k">function</span> <span class="p">():</span> <span class="kt">BillingProvider</span> <span class="p">{</span>
<span class="c1">// Token yok (kendinden host edilen kurulum veya test ile) =&gt; bellek içi sahte.</span>
<span class="k">return</span> <span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.token'</span><span class="p">)</span> <span class="o">===</span> <span class="s1>''</span>
    <span class="o">?</span> <span class="k">new</span> <span class="nc">FakeBillingProvider</span>
    <span class="o">:</span> <span class="nc">BayarCashClient</span><span class="o">::</span><span class="nf">fromConfig</span><span class="p">();</span>

});

<p>Token olmadığında bir Sahte bağlamak, kendinden barındırılan kurulumların faturalandırma kapalı çalışmasına olanak tanır ve tüm test paketinizi ağ olmadan çalıştırır. Hızla kendini amorti eder.</p>

<h2>
    <a name="creating-a-checkout" href="#creating-a-checkout">
    </a>
    Ödeme Oluşturma
</h2>

<p>Paketinizi alan terimleriyle oluşturun, imzalayın, gönderin, yönlendirin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nv">$payload</span> <span class="o">=</span> <span class="nb">array_filter</span><span class="p">([</span>
<span class="s1>'portal_key'</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">client</span><span class="o">-&gt;</span><span class="nf">portalKey</span><span class="p">(),</span>
<span class="s1>'order_number'</span> <span class="o">=&gt;</span> <span class="nv">$externalId</span><span class="p">,</span> <span class="c1">// korelasyon anahtarı — max 30 karakter!</span>
<span class="s1>'amount'</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">amountForCycle</span><span class="p">(</span><span class="nv">$plan</span><span class="p">,</span> <span class="nv">$cycle</span><span class="p">),</span> <span class="c1">// "49.00"</span>
<span class="s1>'payer_name'</span> <span class="o">=&gt;</span> <span class="nv">$ws</span><span class="o">-&gt;</span><span class="n">name</span><span class="p">,</span>
<span class="s1>'payer_email'</span> <span class="o">=&gt;</span> <span class="nv">$ws</span><span class="o">-&gt;</span><span class="n">owner</span><span class="o">?-&gt;</span><span class="n">email</span> <span class="o">??</span> <span class="k">throw</span> <span class="k">new</span> <span class="nc">\RuntimeException</span><span class="p">(</span><span class="s1>'No owner email.'</span><span class="p">),</span>
<span class="s1>'payment_channel'</span> <span class="o">=&gt;</span> <span class="nc">Bayarcash</span><span class="o">::</span><span class="no">FPX</span><span class="p">,</span>
<span class="s1>'return_url'</span> <span class="o">=&gt;</span> <span class="nv">$returnUrl</span><span class="p">,</span>
<span class="s1>'callback_url'</span> <span class="o">=&gt;</span> <span class="p">(</span><span class="n">string</span><span class="p">)</span> <span class="nf">config</span><span class="p">(</span><span class="s1>'bayarcash.callback_url'</span><span class="p">),</span>

], fn ($v) => $v !== null && $v !== ”);

if (($secret = (string) config(’bayarcash.secret’)) !== ’ ‘) {
$payload[’checksum’] = $this->client->checksum($payload);
}

$response = $this->client->createPaymentIntent($payload);
return redirect($response->url); // barındırılan ödeme

<p>İki noktada durmalıyız:</p>

<p><strong><code>order_number</code> korelasyon anahtarınızdır</strong> — ödemenin gittiği tek alan ve her geri çağırmada geri gelir. BayarCash bunu <strong>30 karakter</strong> ile sınırlar, bu yüzden sadece yeterince kodlayın ve benzersiz tutun:</p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// çok kötü olan "wau-{8}-business-a-{6}" == tam 30 karakter</span>

return sprintf(’wau-%s-%s-%s-%s’,
substr($ws->uuid, 0, 8), $plan->tier->value, substr($cycle, 0, 1), bin2hex(random_bytes(3)));

<p><strong>Yönlendirmeden önce <code>pending</code> bir yerel kaydı kalıcı hale getirin</strong>, <code>external_id</code> ile damgalanmış. Eğer webhook, yönlendirmeniz bitmeden önce gelirse (oluyor), güncellenecek kayıt zaten oradadır.</p>

<h2>
    <a name="handling-the-callback-and-webhook" href="#handling-the-callback-and-webhook">
    </a>
    Geri çağırmayı ve webhook'u işleme
</h2>

<p>BayarCash, iki şekilde geri konuşur: <strong>sunucu-sunucu geri çağırma</strong> (<code>callback_url</code>, otoriter — gerçeğinizin kaynağı) ve <strong>tarayıcı geri URL'si</strong> (<code>return_url</code>, bir uzlaştırma güvenlik ağı — bekleyen sunucu geri çağırmasında bir hata olması durumunda hala uzlaştırmalıdır).</p>

<p>Webhook rotasını CSRF'den muaf tutun — sunucu POST işlemi oturum içermez:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nc">Route</span><span class="o">::</span><span class="nf">post</span><span class="p">(</span><span class="s1>'webhooks/bayarcash'</span><span class="p">,</span> <span class="p">[</span><span class="nc">BayarCashCallbackController</span><span class="o">::</span><span class="n">class</span><span class="p">,</span> <span class="s1>'webhook'</span><span class="p">])</span>
<span class="o">-&gt;</span><span class="nf">withoutMiddleware</span><span class="p">([</span><span class="nc">ValidateCsrfToken</span><span class="o">::</span><span class="n">class</span><span class="p">]);</span>

<p>Öncelikle imzayı doğrulayın — BayarCash, her biri kendi doğrulayıcısına sahip <strong>üç yük biçimi</strong> gönderir. Bir işaret alanına göre yönlendirin:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nv">$verified</span> <span class="o">=</span> <span class="k">match</span> <span class="p">(</span><span class="kc">true</span><span class="p">)</span> <span class="p">{</span>
<span class="k">isset</span><span class="p">(</span><span class="nv">$payload</span><span class="p">[</span><span class="s1>'record_status'</span><span class="p">])</span> <span class="o">=&gt;</span> <span class="nv">$sdk</span><span class="o">-&gt;</span><span class="nf">verifyPreTransactionCallbackData</span><span class="p">(</span><span class="nv">$payload</span><span class="p">,</span> <span class="nv">$secret</span><span class="p">),</span> <span class="c1">// DD kaydı</span>
<span class="k">isset</span><span class="p">(</span><span class="nv">$payload</span><span class="p">[</span><span class="s1>'status'</span><span class="p">])</span>        <span class="o">=&gt;</span> <span class="nv">$sdk</span><span class="o">-&gt;</span><span class="nf">verifyTransactionCallbackData</span><span class="p">(</span><span class="nv">$payload</span><span class="p">,</span> <span class="nv">$secret</span><span class="p">),</span>    <span class="c1">// ödeme</span>
<span class="k">default</span>                          <span class="o">=&gt;</span> <span class="nv">$sdk</span><span class="o">-&gt;</span><span class="nf">verifyReturnUrlCallbackData</span><span class="p">(</span><span class="nv">$payload</span><span class="p">,</span> <span class="nv">$secret</span><span class="p">),</span>      <span class="c1">// geri URL</span>

};
if ($verified !== true) { return null; } // arayıcı 401 döner

<p>Sonra, tamsayı durumunu kendi kelime dağarcığınıza bir kez dönüştürün — bu sayede tamsayılar asla dışarı çıkmaz:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="nv">$status</span> <span class="o">=</span> <span class="k">match</span> <span class="p">(</span><span class="n">int</span><span class="p">(</span><span class="nv">$payload</span><span class="p">[</span><span class="s1>'status'</span><span class="p">])</span> <span class="p">){</span>
<span class="mi">3</span> <span class="o">=&gt;</span> <span class="nc">PaymentStatus</span><span class="o">::</span><span class="nc">Completed</span><span class="p">,</span> <span class="c1">// umursadığınız</span>
<span class="k">default</span> <span class="o">=&gt;</span> <span class="nc">PaymentStatus</span><span class="o">::</span><span class="nc">Failed</span><span class="p">,</span>

};

 <blockquote>
    <p><strong>Unutmayın — durum haritanızı mevcut belgelere karşı doğrulayın.</strong> <code>3 = başarılı</code> sabittir; başarısız/pending/iptal sayıları SDK sürümleri arasında değişebilir. Haritanızı API sürümünüz için sabitleyin ve bir test ile kaplayın.</p>
</blockquote>

<h3>
    <a name="the-golden-webhook-rule" href="#the-golden-webhook-rule">
    </a>
    Altın webhook kuralı
</h3>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">public</span> <span class="k">function</span> <span class="n">webhook</span><span class="p">(</span><span class="kt">Request</span> <span class="nv">$request</span><span class="p">):</span> <span class="kt">JsonResponse</span>

{
$result = $this->gateway->handleWebhook($request);

<span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv">$result</span><span class="o">-&gt;</span><span class="n">processed</span><span class="p">)</span> <span class="p">{</span>
    <span class="nc">Log</span><span class="o">::</span><span class="nf">channel</span><span class="p">(</span><span class="s1>'daily'</span><span class="p">)</span><span class="o">-&gt;</span><span class="nf">warning</span><span class="p">(</span><span class="s1>'BayarCash webhook ignored'</span><span class="p">,</span> <span class="p">[</span><span class="s1>'message'</span> <span class="o">=&gt;</span> <span class="nv">$result</span><span class="o">-&gt;</span><span class="n">message</span><span class="p">]);</span>
<span class="p">}</span>

<span class="c1">// Zayıf bir başarısızlık durumunda bile 200 döndürün. BayarCash, non-2xx üzerinde yeniden dener,</span>
<span class="c1">// bu yüzden 500 olursa 40 kez arttırır. Loglayın, OK döndürün, uzlaştırın.</span>
<span class="k">return</span> <span class="nf">response</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">json</span><span class="p">([</span><span class="s1>'processed'</span> <span class="o">=&gt;</span> <span class="nv">$result</span><span class="o">-&gt;</span><span class="n">processed</span><span class="p">]);</span>

}

Laravel’da BayarCash (FPX) Kurulumunu Doğru Şekilde Yapma

Sanal Medya

Son Eklenenler

Qi Fan Fan | The Verge — Yeni Nesil Qi Fan ile Tanışın

Kuyruk Çöküşlerini Önleme: Laravel’de Ölü Mektup Kuyrukları

Jensen Huang’ın imzalı deri ceketi, yardım müzayedesinde $60,000’a satılacak

Geliştirici Kaydı: 2026-07-03 — idempotent senkronizasyonlar, izlenebilir e-posta ve boşaltma değil silme

PC Yapımı İçin 144’ü 1 Arada Elektrikli Tornavida Seti, 40$ Altında

GitHub, Sony’nin fiziksel medyayı yok saymasına karşı Repo CD’ler sunuyor

Siber güvenlik, yapay zeka ve savunma sanayiinden; finans ve sinema dünyasına uzanan geniş bir yelpaze. Teknomers; teknoloji, strateji ve yazılım dünyasını sade bir dille sizlerle buluşturuyor.

Kurumsal

Kategoriler

Populer