PHP və Laravel-də Kapital Bank ödənişləri: kapitalbank-checkout

Kapital Bank vasitəsilə kartla ödəniş qəbul etmək Kapital Bank / Birbank Checkout API ilə işləmək deməkdir: OAuth2 tokeni almaq, ödəniş yaratmaq, müştərini bankın səhifəsinə yönləndirmək, nəticəni yoxlamaq, geri qaytarmaları emal etmək və bankın bildirişlərini yoxlamaq. Bütün bunları açıq PHP kitabxanasında topladıq: learning-machine/kapitalbank-checkout. Bu məqalədə onun köməyi ilə PHP və Laravel-də Kapital Bank ödənişini necə qəbul etməyi və hansı detallara diqqət yetirmək lazım olduğunu göstəririk.

Paket nə edir

• OAuth2 tokeni istənilən PSR-16 keşi vasitəsilə keşləməklə, beləliklə token hər sorğu üçün yenidən alınmır.
• Ödənişin yaradılması və müştərinin bankın ödəniş səhifəsinə yönləndirilməsi.
• Ödənişin statusu: Pending, Succeeded, Canceled və ya Unknown.
• Tam və qismən geri qaytarmalar.
• Webhook yoxlanışı: X-Signature başlığında base64 ilə kodlaşdırılmış HMAC-SHA256 imzası.
• Freymvorkdan asılı olmayan nüvə PSR-18, PSR-17 və PSR-16 standartları üzərində, üstəlik avtomatik aşkarlanan, istəyə bağlı Laravel inteqrasiyası.

Paket PHP 8.1 və ya daha yeni versiya tələb edir və MIT lisenziyası ilə yayımlanır.

Quraşdırma

Paket Packagist-dədir, ona görə onu bir Composer əmri ilə quraşdırmaq olar:

composer require learning-machine/kapitalbank-checkout

Sadə PHP-də ödənişin yaradılması

Məlumatlarınızla klient yaradın. Nümunədə preprod mühiti istifadə olunur, https://precheckout.kapitalbank.az/api; production mühitində baza URL https://checkout.kapitalbank.az/api-dir.

use LearningMachine\KapitalBank\Checkout\Amount;
use LearningMachine\KapitalBank\Checkout\CheckoutClient;

$client = CheckoutClient::fromConfig([
    'base_url' => 'https://precheckout.kapitalbank.az/api',
    'client_id' => getenv('KAPITALBANK_CLIENT_ID'),
    'client_secret' => getenv('KAPITALBANK_CLIENT_SECRET'),
    'merchant_id' => getenv('KAPITALBANK_MERCHANT_ID'),
    'terminal_id' => getenv('KAPITALBANK_TERMINAL_ID'),
], cache: $psr16Cache);

$payment = $client->createPayment(
    Amount::fromDecimal('12.50'),
    'Order #123',
    'https://shop.example/payment/return',
    $idempotencyKey
);

// $payment->id və $payment->idempotencyKey dəyərlərini sifarişlə birlikdə saxlayın
header('Location: ' . $payment->redirectUrl());

Məbləğlər dəyər obyektləridir: Amount::fromDecimal('12.50') və ya eyni məbləğ qəpiklərlə Amount::fromMinor(1250). Valyuta standart olaraq AZN-dir. Onluq məbləği sətir kimi ötürmək üzən nöqtəli ədədlərin gözlənilməz nəticələrindən qoruyur.

İdempotentlik açarı bu ödəniş cəhdi üçün yaratdığınız və sifarişlə birlikdə saxladığınız unikal dəyərdir. Aşağıda göstərildiyi kimi, təhlükəsiz təkrar cəhdi məhz o mümkün edir.

Statusun yoxlanılması

Müştəri qayıdış URL-inizə qayıdanda təkcə yönləndirməyə etibar etməyin: banka sorğu göndərin.

$p = $client->getPayment($paymentId);
$p->status; // Status::Pending, Status::Succeeded, Status::Canceled və ya Status::Unknown

Yalnız Succeeded pulun köçürüldüyü deməkdir. Unknown halında bankdan gələn orijinal sətir $p->rawStatus-da mövcuddur.

Geri qaytarmalar

$refund = $client->refund($paymentId, Amount::fromDecimal('2.50'), $refundRowUuid);

Ötürdüyünüz məbləğ nə qədərin geri qaytarılacağını müəyyən edir: bütün məbləğ və ya onun bir hissəsi. Üçüncü arqument öz verilənlər bazanızdakı geri qaytarma qeydinin UUID-sidir. Bilməyə dəyər bir detal: açıq API sorğu kitabçası yalnız geri qaytarma obyektini təsvir edir, sorğunu yox. Real API-nin qəbul etdiyi sorğu gövdəsi {"id": "<payment uuid>", "amount": 2.5}-dir və paket məhz bunu göndərir; onu jurnala yazmaq istəsəniz, $refund->requestBody onu göstərir.

Webhook-lar

Bank serverinizi ödəniş hadisələri barədə xəbərdar edir. Gövdədəki hər hansı məlumata etibar etməzdən əvvəl imzanı yoxlayın:

use LearningMachine\KapitalBank\Checkout\Webhook\WebhookParser;

$parser = new WebhookParser(getenv('KAPITALBANK_WEBHOOK_SECRET'));
$event = $parser->parse($rawBody, $request->headers->get('X-Signature'));

if ($event->isSucceeded()) {
    // sifarişi idempotent şəkildə ödənilmiş kimi qeyd edin
}
// həmişə HTTP 200 ilə cavab verin, əks halda bank bildirişi yenidən göndərir

Sorğunun xam gövdəsini, alındığı kimi ötürün; yenidən kodlaşdırılmış JSON sətri imzaya uyğun gəlməyəcək. İmza səhvdirsə, parse() InvalidWebhook istisnası atır. Etibarlı hadisələrə, ləğv edilmiş ödənişlər də daxil olmaqla, hər halda HTTP 200 ilə cavab verin və ödənişin qeydə alınmasını idempotent edin, çünki eyni hadisə bir neçə dəfə gələ bilər.

Pul üçün vacib olan xətalar

use LearningMachine\KapitalBank\Checkout\Exception\AuthenticationFailed;
use LearningMachine\KapitalBank\Checkout\Exception\BankRejected;
use LearningMachine\KapitalBank\Checkout\Exception\OutcomeUnknown;

try {
    $payment = $client->createPayment($amount, $description, $returnUrl, $idempotencyKey);
} catch (BankRejected $e) {
    // bank xəta ilə cavab verdi; banka $e->error->traceId dəyərini bildirin
    // 5xx cavablarında $e->isServerError() true qaytarır
} catch (OutcomeUnknown $e) {
    // vaxt bitdi və ya bağlantı kəsildi: bank sorğunu emal etmiş OLA BİLƏR
} catch (AuthenticationFailed $e) {
    // token sorğusu uğursuz oldu; pulla bağlı heç nə göndərilməyib
}

OutcomeUnknown xüsusi düşünülməli haldır. Sorğu banka çatmış da ola bilər, çatmamış da, ona görə heç vaxt yoxlamadan yeni ödəniş yaratmayın. Ya eyni idempotentlik açarı ilə təkrar cəhd edin, ya da ödənişi getPayment() ilə yoxlayın. BankRejected istisnasında bankın dəstək xidmətinin sorğunuzu tapmaq üçün istifadə edə biləcəyi traceId var.

Laravel inteqrasiyası

Laravel-də servis provayderi avtomatik aşkarlanır. Konfiqurasiyanı dərc edin:

php artisan vendor:publish --tag=kapitalbank-config

və .env faylını doldurun:

KAPITALBANK_BASE_URL=https://precheckout.kapitalbank.az/api
KAPITALBANK_CLIENT_ID=
KAPITALBANK_CLIENT_SECRET=
KAPITALBANK_MERCHANT_ID=
KAPITALBANK_TERMINAL_ID=
KAPITALBANK_WEBHOOK_SECRET=

Bundan sonra CheckoutClient və ya WebhookParser obyektlərini lazım olan yerə inject edin; hər ikisi singleton kimi qeydiyyatdan keçir. Webhook kontrollerində xam gövdəni $request->getContent() ilə oxuyun və webhook marşrutunu CSRF qorunmasından çıxarmağı unutmayın. Paket Laravel-in Http::fake() metodu ilə də işləyir, beləliklə ödəniş prosesinizi banka sorğu göndərmədən testlərlə əhatə edə bilərsiniz.

İstifadə edin və ya inteqrasiyanı bizə həvalə edin

Paket GitHub-da açıq mənbəlidir; issue və pull request-lər xoş qarşılanır. Ətraflı məlumat layihə səhifəsində və açıq mənbə bölməmizdədir. Ödənişləri saytınıza və ya sisteminizə inteqrasiya etməkdə köməyə ehtiyacınız varsa, tapşırığınızı təsvir edin.