Bepaid

04.08.2026

Осы бетте

Қосылу жолы

bePaid төлем жүйесін қосу үшін сізге Store ID, құпия кілт және ашық кілт қажет болады. Осы деректерді алғаннан кейін MaviBot бағдарламасындағы төлем жүйесі параметрлеріне өтіңіз.

Store ID, құпия кілт және ашық кілт алу үшін bePaid техникалық қолдау қызметіне хабарласыңыз.

MaviBot бағдарламасында Acquiring бөлімін ашыңыз, bePaid таңдаңыз және алған деректеріңізді енгізіңіз.

Ескерту: Соңғы өріс — бұл пайдалану еліне байланысты API мекенжайын таңдайтын қосқыш: Беларусь немесе Ресей.

Төлем сілтемесін қалай жасауға болады

Төлем сілтемесін жасау үшін payment_sum айнымалысына мән беріңіз (мысалы: 150 немесе 100.55; ондық бөлгіш ретінде нүктені пайдаланыңыз).

payment_sum айнымалысы орнатылғаннан кейін bepaid_pay_url айнымалысы автоматты түрде жасалады. Бұл айнымалыны хабарламадағы сілтеме ретінде көрсетуге немесе "Төлеу" мәтіні бар түймеде пайдалануға болады.

Функция параметрі	Сипаттамасы	Қосымша ақпарат
currency	ISO 4217 форматындағы төлем валютасы.	Мысалы: USD
language	Төлем бетінің тілі. Әдепкі: `en`.	Рұқсат етілген мәндер: • `en` — Ағылшын • `es` — Испан • `tr` — Түрік • `de` — Неміс • `it` — Итальян • `ru` — Орыс • `zh` — Қытай • `fr` — Француз • `da` — Дат • `sv` — Швед • `no` — Норвег • `fi` — Фин • `pl` — Поляк • `ja` — Жапон • `uk` — Украин • `be` — Беларусь • `ka` — Грузин • `ro` — Румын
payment_description	Төлем сипаттамасы.	—
link_expired	Төлем сілтемесінің мерзімінің аяқталуы. Мерзімнің аяқталу күнін `dd.mm.yyyy` форматында орнатыңыз (мысалы: `25.06.2025`). Әдепкі бойынша, төлем 24 сағат ішінде аяқталуы керек.	Қайта бағыттау кезінде айнымалыларды тағайындау өрісін де пайдалануға болады: • `link_expired = current_date + 2` — сілтеме 00:00-ге дейін 2 күн жарамды болады. • Мерзімнің аяқталуының нақты күні мен уақытын `dd.mm.yyyy hh:mm` форматында көрсетуге болады (мысалы: `25.06.2025 12:23`). Стандартты айнымалыларды да пайдалануға болады. 30 минут жарамды сілтемеге мысал: `python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n`
russian_host	Ресейлік bePaid хостта тіркелген дүкеннің көрсеткіші. Егер дүкеніңіз bepaid.tech сайтында тіркелген болса, бұл параметрді `1` мәніне орнатыңыз.	Беларусь хостына ауысу үшін бұл параметрді `""` (бос мән) мәніне орнатыңыз.
test_payments	Сынақ төлемдерін қосады. Төлем сілтемесін жасамас бұрын осы айнымалыға кез келген мән беріңіз.	—
bepaid_attempts	Төлем әрекеттерінің санын көрсетеді. Әдепкі бойынша, 1 әрекетке рұқсат етіледі.	—
customer_data	Төлеушінің first_name, last_name және email мәліметтерін қамтитын JSON нысаны. Бұл ақпарат төлем түбіртегін жіберу үшін қажет және төлем бетінде өңделуі мүмкін.	Параметр JSON пішіміндегі нысан ретінде берілуі керек. Мысал: `python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n`
bepaid_contract (шартты түрде міндетті)	Токен негізіндегі төлемдер үшін төлем мақсаты.	Рұқсат етілген мәндер: • `recurring` — белгіленген кестесі бар қайталанатын төлемдер үшін. • `card_on_file` — бір реттік немесе тұрақты емес төлемдер үшін, мысалы, қызмет көрсетілгеннен кейін клиенттен ақы алу.

Төлем сілтемесінің мысалы:

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

payment_sum мәнін бермес бұрын, төлемді теңшеу үшін қосымша қосымша айнымалыларды анықтауға болады.

Әдепкі бойынша, төлем валютасы Беларусь рублі (BYN) болып табылады. Егер басқа валютаны пайдаланғыңыз келсе, currency айнымалысына мән беріңіз.

Төлем аяқталғаннан кейін клиентке bepaid_callback_data айнымалысы қосылады. Онда аяқталған транзакция үшін төлем жүйесінің жауабы бар.

Осы сөздіктен қажетті мәндерді get() функциясын пайдаланып алуға болады.

Төлемдерді қалай тексеруге болады

Сынақ төлемін орындау үшін payment_sum айнымалысын орнатпастан бұрын test_payments айнымалысына кез келген мән беріңіз.

Маңызды: Ботыңызды нақты режимге ауыстырмас бұрын test_payments айнымалысын жойыңыз.

Сынақ карталары

Карта нөмірі	Нәтиже
`4200000000000000`	Сәтті төлем
`4005550000000019`	Сәтсіз төлем

Төлем сілтемесін жасау мысалы

Келесі мысал 100 Беларусь рубліне (әдепкі валюта) төлем сілтемесін жасайды.

Ескерту: Алдымен кез келген қосымша конфигурация айнымалыларын тағайындаңыз, содан кейін payment_sum мәнін беріңіз. Бұл айнымалыларды жұмыс ағымыңызда бұрын да тағайындауға болады — олар бір блокта болуы міндетті емес.

Соңында, bepaid_pay_url айнымалысын қажетті жерде көрсетіңіз. Онда жасалған төлем сілтемесі бар.

Жазылымдарды басқару

bePaid интеграциясы клиенттеріңізге жазылымдар жасауға мүмкіндік береді.

MaviBot бағдарламасында бұл функционалды пайдаланбас бұрын, bePaid тіркелгіңізде жазылым жоспарын жасаңыз.

Егер тіркелгіңізде Жоспарлар және Жазылымдар бөлімдері қолжетімді болмаса, тіркелгі менеджеріңізге хабарласыңыз.

Жазылымды жасау және төлем сілтемесін жасау

get_bepaid_subscription_url функциясын пайдаланыңыз және plan_id параметрін беріңіз.

Функция жазылымды жасайды және төлем сілтемесін қайтарады.

Жасалған сілтемені клиентке жіберіңіз және төлемнің аяқталуын күтіңіз.

Сәтті төлемнен кейін:

жазылым белсендіріледі;
мәміле келесі айнымалыларды алады:
- bepaid_subscription_id;
- bepaid_subscription_status;
ботқа кері шақыру жіберіледі (Нәтижені қалай өңдеу керек бөлімін қараңыз).

Жазылым ақпаратын алу

Ағымдағы жазылым ақпаратын алу үшін get_bepaid_subscription_info функциясын пайдаланыңыз.

subscription_id параметрін беріңіз. Оның мәнін bepaid_subscription_id айнымалысынан алуға болады.

Жазылымды болдырмау

Жазылымды болдырмау үшін cancel_bepaid_subscription функциясын пайдаланыңыз.

Функция бір параметрді қабылдайды:

subscription_id — мәнін bepaid_subscription_id айнымалысынан алуға болады.

Сәтті болдырмаудан кейін:

bepaid_subscription_status айнымалысы "canceled" мәніне орнатылады;
ботқа кері шақыру жіберіледі (Нәтижені қалай өңдеу керек бөлімін қараңыз).

Жазылым күйлері

Күй	Сипаттамасы
trial	Белсенді немесе болдырылған сынақ мерзімі жазылымы.
active	Төлем уақытында жасалған белсенді жазылым.
failed	Сәтсіз жазылым. bePaid келесі төлемді өңдей алмады.
error	bePaid төлемді өңдеуге әрекеттенген кезде қате орын алды.
canceled	Жазылым болдырылды және енді белсенді емес.

Қайталанатын төлемдер

Сондай-ақ, bePaid тіркелгіңізде жазылым жоспарын жасамай-ақ қайталанатын төлемдерді орнатуға болады.

Ол үшін сізге клиенттің карта токені қажет.

Карта токенін алу

Клиенттің карта токенін алу үшін клиент payment_sum айнымалысы арқылы жасалған төлем сілтемесін пайдаланып бастапқы төлемді аяқтауы керек.

payment_sum мәнін бермес бұрын, болашақ токен негізіндегі төлемдердің мақсатын анықтау үшін bepaid_contract айнымалысын орнатыңыз.

Қолдау көрсетілетін мәндер:

recurring — алдын ала анықталған кестесі бар қайталанатын төлемдер үшін.
card_on_file — бір реттік немесе тұрақты емес төлемдер үшін, мысалы, қызмет көрсетілгеннен кейін клиенттен ақы алу.

Ескерту: card_on_file опциясын барлық эквайринг банктері қолдамайды. Егер бұл опцияны пайдалануды жоспарласаңыз, тіркелгі менеджеріңізге хабарласыңыз.

Сәтті төлемнен кейін мәмілеге bepaid_client_card_token айнымалысы қосылады. Ол клиенттің карта токенін сақтайды, оны клиенттің қатысуынсыз болашақ төлемдер үшін пайдалануға болады.

Әрі қарай, жұмыс ағымыңызды конфигурациялаңыз, клиенттен ақы алу үшін қажетті күн немесе шартты анықтаңыз және make_bepaid_token_payment функциясын шақырыңыз.

Параметрлер келесі ретпен берілуі керек:

amount → currency → description → contract

Параметрлердің сипаттамалары

contract параметрінің мәні бастапқы төлем сілтемесін жасау кезінде көрсетілген мәнге дәл сәйкес келуі керек.

Параметр	Сипаттамасы
amount (міндетті)	Төлем сомасы. Мән бүтін немесе ондық сан болуы керек, мысалы: `100` немесе `100.5`.
currency (міндетті)	ISO 4217 форматындағы төлем валютасы, мысалы: `USD`.
description (міндетті)	Төлем сипаттамасы, мысалы: `"Хобби клубына қатысу үшін апталық жазылым төлемі"`.
contract (міндетті)	Токен бойынша төлем мақсаты. Рұқсат етілген мәндер: `recurring` немесе `card_on_file`.

Егер төлем сәтті болса:

функция "bePaid токені арқылы сәтті төлем" хабарламасын қайтарады;
бот сәтті төлем кері шақыруын алады;
bepaid_token_payment_completed айнымалысы True мәніне орнатылады.

Егер төлем сәтсіз болса:

функция сәтсіздік себебін сипаттайтын хабарламаны қайтарады;
бот _fail жұрнағы бар кері шақыруды алады;
bepaid_token_payment_completed айнымалысы False мәніне орнатылады.

Егер банк клиенттің қосымша тексеруін талап етсе, функция клиент 3-D Secure аутентификациясын аяқтай алатын сілтемені қайтарады.

Нәтижені қалай өңдеу керек

Клиенттің әрекеттеріне жауап ретінде бот құпия кілттің бірінші 20 таңбасынан және операция түрі мен нәтижесін көрсететін жұрнақтан тұратын кері шақыруларды алады.

Кері шақыру жүйеде пайдаланушы хабарламасы ретінде пайда болады, бірақ ол клиентке көрінбейді.

Төлем кері шақырулары

Бір реттік төлемдер үшін бот келесі кері шақырулардың бірін алады:

keyNumber_success — сәтті төлем.
keyNumber_fail — сәтсіз төлем.

Сондай-ақ, төлем нәтижесін келесі айнымалылар арқылы бақылауға болады:

bepaid_payment_completed — клиент төлемді аяқтады.
bepaid_token_payment_completed — клиенттің карта токені арқылы автоматты төлем аяқталды.

Жазылым кері шақырулары

Жазылым сәтті белсендірілгеннен кейін, бастапқы төлем кезінде немесе қайталанатын төлем кезінде бот алады:

keyNumber_success

Егер жазылым болдырылса, бот алады:

keyNumber_canceled

Егер жазылым төлемі сәтсіз болса, бот алады:

keyNumber_fail