Açık Kaynak Bir Telebirr SDK’sı Oluşturdum: Günlerce İmza Hatalarıyla Mücadele Ettikten Sonra

Laravel veya PHP ile Telebirr entegrasyonu gerçekleştirdiyseniz, bu hatayı muhtemelen görmüşsünüzdür:

60200099 Verify the sign field failed
    

Başlangıçta basit görünüyor.

Sonra saatlerce hata ayıklama yaparsınız:

• RSA padding
• parametre sıralaması
• webhook doğrulaması
• H5 imzalama kuralları
• PEM formatlama
• sanal ve üretim arasındaki farklar

…ve hiçbir şey tutarlı bir şekilde çalışmıyor.

Bu sorunlarla tekrar tekrar uğraştıktan sonra, otomatik olarak etkileşim sorunlarını yöneten üretime odaklanmış bir Telebirr PHP & Laravel SDK’sı geliştirmeye karar verdim.

GitHub Deposu

https://github.com/OgBek/Telebirr-laravel-package-sdk

Gerçek API çağrıları kolaydır.

Diğer zorluk ise imzaların güvenilir bir şekilde çalışmasını sağlamaktı:

• sanal ortam
• üretim ortamı
• farklı PHP ortamları
• Laravel istek işleme
• H5 yönlendirme imzalama

Çevrimiçi birçok entegrasyon örneğinin:

• yanlış alanları imzaladığını
• tutarsız sıralama kullandığını
• RSA-PSS ile PKCS1’i karıştırdığını
• tekrar korumasını göz ardı ettiğini
• üretimde başarısız olduğunu, sandbox’ın çalıştığı durumları gözlemledim.

Örneğin, Telebirr H5 imzalama yalnızca bu alanları bekler:

appid
    merch_code
    nonce_str
    prepay_id
    timestamp
    

Yanlışlıkla şunlar gibi alanları:

• version
• trade_type
• redirect_url

imzalı payload’un içine eklerseniz, rastgele imza hataları alırsınız.

Bu tek sorun bile gereksiz bir hata ayıklama süresi kaybına neden oldu.

Paket artık otomatik olarak şunları yönetir:

• RSA-PSS imzalama
• İsteğe bağlı PKCS1 desteği
• Deterministik rekürran sıralama
• Webhook doğrulaması
• Replay saldırı koruması
• Zaman damgası doğrulaması
• Akıllı PEM anahtar yükleme
• Laravel entegrasyonu
• Vanilla PHP uyumluluğu

composer require bekambeyene/telebirr
    

Yapılandırmayı yayınlayın:

php artisan vendor:publish --tag="telebirr-config"
    

Bir H5 ödemesi oluşturun:

$paymentUrl = Telebirr::createOrder(
        'Premium Subscription',
        250.00,
        'ORDER-' . uniqid()
    );

    return redirect()->away($paymentUrl);
    

Webhook doğrulaması:

$payload = Telebirr::handleWebhook($request);
    

SDK, otomatik olarak şunları doğrular:

• imzalar
• zaman damgaları
• nonce tekrar denemeleri

Birçok geliştirici için rahatsız edici bir sorun, .env anahtar formatlama durumuydu.

Bazı geliştiriciler:

• ham anahtarları kaydeder
• base64 kullanır
• dosya yolları kullanır
• çok satırlı formatlamayı yanlışlıkla bozar

SDK şimdi şunları destekliyor:

TELEBIRR_PRIVATE_KEY="file:///var/www/keys/private_key.pem"
    

ve ayrıca ham/base64 formatlarını otomatik olarak destekler.

Hızla öğrendiğim bir şey:

SAnal ortamda başarı, üretim ortamında başarı garantisi değildir.

Üretim Telebirr ortamları, genel olarak daha sıkı davranma eğilimindedir:

• padding modları
• zaman damgaları
• payload sıralaması
• imza tutarlılığı

Bu nedenle paket, deterministik davranış üzerine yoğunlaşmaktadır.

SDK şunları içerir:

• tekrar saldırı tespiti
• zaman damgası geçerlilik doğrulaması
• katı webhook doğrulaması
• deterministik kanonizasyon
• yapılandırılabilir RSA padding

Laravel ve üretim etkileşimine odaklanan iyi bakımlı çok fazla açık kaynak Telebirr entegrasyonu yoktur.

Geliştiricilerin tekrar tekrar kriptografik uç durumları hata ayıklamak zorunda kalmadan güvenebilecekleri bir şey inşa etmek istedim.

Depo

https://github.com/OgBek/Telebirr-laravel-package-sdk

Geri bildirimler, sorunlar ve katkılar için her zaman açıktır.

laravel php opensource payments ethiopia sdk