Nasıl Bağlanır

bePaid ödeme sistemini bağlamak için bir Mağaza Kimliği, gizli anahtar ve genel anahtar gerekir. Bu kimlik bilgilerini aldıktan sonra MaviBot'taki ödeme sistemi ayarlarına gidin.

Mağaza Kimliği, gizli anahtar ve genel anahtar almak için bePaid teknik desteğiyle iletişime geçin.

MaviBot'ta Tahsilat bölümünü açın, bePaid'i seçin ve aldığınız kimlik bilgilerini girin.

Not: Son alan, kullanım ülkesine bağlı olarak API uç noktasını seçen bir anahtardır: Belarus veya Rusya.

Ödeme Bağlantısı Nasıl Oluşturulur

Bir ödeme bağlantısı oluşturmak için payment_sum değişkenine bir değer atayın (örneğin: 150 veya 100.55; ondalık ayırıcı olarak nokta kullanın).

payment_sum değişkeni ayarlandıktan sonra bepaid_pay_url değişkeni otomatik olarak oluşturulur. Bu değişkeni bir mesajda bağlantı olarak görüntüleyebilir veya "Öde" metniyle bir düğmede kullanabilirsiniz.

Fonksiyon Parametresi	Açıklama	Daha Fazla Bilgi
currency	ISO 4217 formatında ödeme para birimi.	Örneğin: USD
language	Ödeme sayfası dili. Varsayılan: `en`.	İzin verilen değerler: • `en` — İngilizce • `es` — İspanyolca • `tr` — Türkçe • `de` — Almanca • `it` — İtalyanca • `ru` — Rusça • `zh` — Çince • `fr` — Fransızca • `da` — Danca • `sv` — İsveççe • `no` — Norveççe • `fi` — Fince • `pl` — Lehçe • `ja` — Japonca • `uk` — Ukraynaca • `be` — Belarusça • `ka` — Gürcüce • `ro` — Rumence
payment_description	Ödeme açıklaması.	—
link_expired	Ödeme Bağlantısı Süre Sonu. Son kullanma tarihini `gg.aa.yyyy` biçiminde ayarlayın (örneğin: `25.06.2025`). Varsayılan olarak ödemenin 24 saat içinde tamamlanması gerekir.	Ayrıca Yönlendirmede Değişken Ata alanını da kullanabilirsiniz: • `link_expired = current_date + 2` — bağlantı 00:00'a kadar 2 gün geçerli olacaktır. • `gg.aa.yyyy ss:dd` biçiminde tam bir son kullanma tarihi ve saati belirtebilirsiniz (örneğin: `25.06.2025 12:23`). Standart değişkenler de kullanılabilir. 30 dakika geçerli bir bağlantı örneği: `python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n`
russian_host	Rus bePaid sunucusunda kayıtlı bir mağaza göstergesi. Mağazanız bepaid.tech üzerinde kayıtlıysa bu parametreyi `1` olarak ayarlayın.	Belarus sunucusuna geçmek için bu parametreyi `""` (boş değer) olarak ayarlayın.
test_payments	Test ödemelerini etkinleştirir. Ödeme bağlantısını oluşturmadan önce bu değişkene herhangi bir değer atayın.	—
bepaid_attempts	Ödeme deneme sayısını belirtir. Varsayılan olarak 1 denemeye izin verilir.	—
customer_data	Ödeyicinin first_name, last_name ve email bilgilerini içeren bir JSON nesnesi. Bu bilgiler ödeme makbuzunu göndermek için gereklidir ve ödeme sayfasında düzenlenebilir.	Parametre JSON biçimli bir nesne olarak iletilmelidir. Örnek: `python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n`
bepaid_contract (koşullu olarak gerekli)	Token tabanlı ödemeler için ödeme amacı.	İzin verilen değerler: • `recurring` — sabit bir programa sahip yinelenen ödemeler için. • `card_on_file` — örneğin, hizmet sağlandıktan sonra müşteriye fatura kesmek gibi tek seferlik veya düzensiz ödemeler için.

Örnek ödeme bağlantısı:

https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

payment_sum değişkenine bir değer atamadan önce, ödemeyi özelleştirmek için ek isteğe bağlı değişkenler tanımlayabilirsiniz.

Varsayılan olarak ödeme para birimi Belarus rublesi (BYN)'dir. Başka bir para birimi kullanmak istiyorsanız currency değişkenine bir değer atayın.

Ödeme tamamlandıktan sonra müşteriye bepaid_callback_data değişkeni eklenir. Bu değişken, tamamlanan işlem için ödeme sistemi yanıtını içerir.

Bu sözlükten gerekli değerleri get() fonksiyonunu kullanarak alabilirsiniz.

Ödemeler Nasıl Test Edilir

Bir test ödemesi gerçekleştirmek için, payment_sum değişkenini ayarlamadan önce test_payments değişkenine herhangi bir değer atayın.

Önemli: Botunuzu canlı moda geçirmeden önce test_payments değişkenini kaldırın.

Test Kartları

Kart Numarası	Sonuç
`4200000000000000`	Başarılı ödeme
`4005550000000019`	Başarısız ödeme

Ödeme Bağlantısı Oluşturma Örneği

Aşağıdaki örnek, 100 Belarus rublesi (varsayılan para birimi) için bir ödeme bağlantısı oluşturur.

Not: Önce ek yapılandırma değişkenlerini atayın, ardından payment_sum değişkenine değer atayın. Bu değişkenler iş akışınızda daha önce de atanabilir; aynı blokta olmaları gerekmez.

Son olarak, bepaid_pay_url değişkenini gereken yerde görüntüleyin. Bu değişken, oluşturulan ödeme bağlantısını içerir.

Abonelik Yönetimi

bePaid entegrasyonu, müşterileriniz için abonelikler oluşturmanıza olanak tanır.

MaviBot'ta bu işlevselliği kullanmadan önce bePaid hesabınızda bir abonelik planı oluşturun.

Hesabınızda Planlar ve Abonelikler bölümleri mevcut değilse, hesap yöneticinizle iletişime geçin.

Abonelik Oluşturma ve Ödeme Bağlantısı Oluşturma

get_bepaid_subscription_url fonksiyonunu kullanın ve plan_id parametresini iletin.

Fonksiyon bir abonelik oluşturur ve bir ödeme bağlantısı döndürür.

Oluşturulan bağlantıyı müşteriye gönderin ve ödemenin tamamlanmasını bekleyin.

Başarılı bir ödemeden sonra:

abonelik etkinleştirilir;
anlaşma aşağıdaki değişkenleri alır:
- bepaid_subscription_id;
- bepaid_subscription_status;
bot'a bir geri arama gönderilir (bkz. Sonuç Nasıl İşlenir).

Abonelik Bilgilerini Alma

Geçerli abonelik bilgilerini almak için get_bepaid_subscription_info fonksiyonunu kullanın.

subscription_id parametresini iletin. Değeri bepaid_subscription_id değişkeninden alınabilir.

Aboneliği İptal Etme

Bir aboneliği iptal etmek için cancel_bepaid_subscription fonksiyonunu kullanın.

Fonksiyon tek bir parametre alır:

subscription_id — değer bepaid_subscription_id değişkeninden alınabilir.

Başarılı bir iptalden sonra:

bepaid_subscription_status değişkeni "canceled" olarak ayarlanır;
bot'a bir geri arama gönderilir (bkz. Sonuç Nasıl İşlenir).

Abonelik Durumları

Durum	Açıklama
trial	Etkin veya iptal edilmiş deneme süresi aboneliği.
active	Zamanında ödeme yapılmış etkin abonelik.
failed	Başarısız abonelik. bePaid bir sonraki ödemeyi işleyemedi.
error	bePaid ödemeyi işlemeye çalışırken bir hata oluştu.
canceled	Abonelik iptal edildi ve artık etkin değil.

Yinelenen Ödemeler

Ayrıca bePaid hesabınızda bir abonelik planı oluşturmadan yinelenen ödemeler ayarlayabilirsiniz.

Bunun için müşterinin kart token'ına ihtiyacınız vardır.

Kart Token'ı Alma

Müşterinin kart token'ını almak için, müşterinin payment_sum değişkeni kullanılarak oluşturulan bir ödeme bağlantısını kullanarak bir ilk ödeme yapması gerekir.

payment_sum değişkenine bir değer atamadan önce, gelecekteki token tabanlı ödemelerin amacını tanımlamak için bepaid_contract değişkenini ayarlayın.

Desteklenen değerler:

recurring — önceden tanımlanmış bir programa sahip yinelenen ödemeler için.
card_on_file — örneğin, hizmet sağlandıktan sonra müşteriye fatura kesmek gibi tek seferlik veya düzensiz ödemeler için.

Not: card_on_file seçeneği tüm tahsilat bankaları tarafından desteklenmez. Bu seçeneği kullanmayı planlıyorsanız hesap yöneticinizle iletişime geçin.

Başarılı bir ödemeden sonra anlaşmaya bepaid_client_card_token değişkeni eklenir. Bu değişken, müşteri etkileşimi olmadan gelecekteki ödemeler için kullanılabilecek müşterinin kart token'ını saklar.

Ardından, iş akışınızı yapılandırın, müşteriye fatura kesmek için gerekli tarihi veya koşulu tanımlayın ve make_bepaid_token_payment fonksiyonunu çağırın.

Parametreler aşağıdaki sırayla iletilmelidir:

tutar → para_birimi → açıklama → sözleşme

Parametre Açıklamaları

contract parametresinin değeri, ilk ödeme bağlantısını oluştururken belirtilen değerle tam olarak eşleşmelidir.

Parametre	Açıklama
amount (gerekli)	Ödeme tutarı. Değer bir tam sayı veya ondalık sayı olmalıdır, örneğin: `100` veya `100.5`.
currency (gerekli)	ISO 4217 formatında ödeme para birimi, örneğin: `USD`.
description (gerekli)	Ödeme açıklaması, örneğin: `"Hobi kulübüne katılım için haftalık abonelik ücreti"`.
contract (gerekli)	Token ile ödeme amacı. İzin verilen değerler: `recurring` veya `card_on_file`.

Ödeme başarılı olursa:

fonksiyon "bePaid tokenı ile başarılı tahsilat" mesajını döndürür;
bot başarılı bir ödeme geri araması alır;
bepaid_token_payment_completed değişkeni True olarak ayarlanır.

Ödeme başarısız olursa:

fonksiyon başarısızlık nedenini açıklayan bir mesaj döndürür;
bot _fail sonekine sahip bir geri arama alır;
bepaid_token_payment_completed değişkeni False olarak ayarlanır.

Banka ek müşteri doğrulaması gerektiriyorsa, fonksiyon müşterinin 3-D Secure kimlik doğrulamasını tamamlayabileceği bir bağlantı döndürür.

Sonuç Nasıl İşlenir

Müşteri eylemlerine yanıt olarak bot, gizli anahtarın ilk 20 karakterinden ve ardından işlem türünü ve sonucunu belirten bir sonekten oluşan geri aramalar alır.

Geri arama, sistemde bir kullanıcı mesajı olarak görünür, ancak müşteri tarafından görülmez.

Ödeme Geri Aramaları

Tek seferlik ödemeler için bot aşağıdaki geri aramalardan birini alır:

keyNumber_success — başarılı ödeme.
keyNumber_fail — başarısız ödeme.

Ayrıca aşağıdaki değişkenleri kullanarak ödeme sonucunu da takip edebilirsiniz:

bepaid_payment_completed — müşteri tarafından tamamlanan ödeme.
bepaid_token_payment_completed — müşterinin kart token'ı kullanılarak tamamlanan otomatik ödeme.

Abonelik Geri Aramaları

Bir abonelik başarıyla etkinleştirildikten sonra, ilk ödeme sırasında veya yinelenen bir ödeme sırasında bot şunları alır:

keyNumber_success

Abonelik iptal edilirse bot şunları alır:

keyNumber_canceled

Bir abonelik ödemesi başarısız olursa bot şunları alır:

keyNumber_fail

Bepaid