Cara Menyambung

Untuk menyambung sistem pembayaran bePaid, anda memerlukan ID Kedai, kunci rahsia, dan kunci awam. Setelah menerima kelayakan ini, pergi ke tetapan sistem pembayaran di MaviBot.

Untuk mendapatkan ID Kedai, kunci rahsia, dan kunci awam, hubungi sokongan teknikal bePaid.

Di MaviBot, buka bahagian Pemerolehan, pilih bePaid, dan masukkan kelayakan yang anda terima.

Nota: Medan terakhir adalah suis yang memilih titik akhir API bergantung pada negara penggunaan: Belarus atau Rusia.

Cara Menjana Pautan Pembayaran

Untuk menjana pautan pembayaran, tetapkan nilai kepada pembolehubah payment_sum (contohnya: 150 atau 100.55; gunakan titik sebagai pemisah perpuluhan).

Setelah pembolehubah payment_sum ditetapkan, pembolehubah bepaid_pay_url dibuat secara automatik. Anda boleh memaparkan pembolehubah ini sebagai pautan dalam mesej atau menggunakannya dalam butang dengan teks "Bayar".

Parameter Fungsi Penerangan Maklumat Lanjut
currency Mata wang pembayaran dalam format ISO 4217. Contohnya: USD
language Bahasa halaman pembayaran. Lalai: en. Nilai yang dibenarkan:
• en — Inggeris
• es — Sepanyol
• tr — Turki
• de — Jerman
• it — Itali
• ru — Rusia
• zh — Cina
• fr — Perancis
• da — Denmark
• sv — Sweden
• no — Norway
• fi — Finland
• pl — Poland
• ja — Jepun
• uk — Ukraine
• be — Belarus
• ka — Georgia
• ro — Romania
payment_description Penerangan pembayaran. —
link_expired Tamat Tempoh Pautan Pembayaran. Tetapkan tarikh tamat tempoh dalam format dd.mm.yyyy (contohnya: 25.06.2025). Secara lalai, pembayaran mesti diselesaikan dalam tempoh 24 jam. Anda juga boleh menggunakan medan Tetapkan Pembolehubah pada Pengalihan Semula:

• link_expired = current_date + 2 — pautan akan sah selama 2 hari sehingga 00:00.

• Anda boleh menentukan tarikh dan masa tamat tempoh yang tepat dalam format dd.mm.yyyy hh:mm (contohnya: 25.06.2025 12:23).

Pembolehubah standard juga boleh digunakan. Contoh untuk pautan yang sah selama 30 minit:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host Penunjuk untuk kedai yang didaftarkan pada hos bePaid Rusia. Tetapkan parameter ini kepada 1 jika kedai anda didaftarkan di bepaid.tech. Untuk bertukar ke hos Belarus, tetapkan parameter ini kepada "" (nilai kosong).
test_payments Mendayakan pembayaran ujian. Tetapkan sebarang nilai kepada pembolehubah ini sebelum mencipta pautan pembayaran. —
bepaid_attempts Menentukan bilangan percubaan pembayaran. Secara lalai, 1 percubaan dibenarkan. —
customer_data Objek JSON yang mengandungi first_name, last_name, dan email pembayar. Maklumat ini diperlukan untuk menghantar resit pembayaran dan boleh diedit pada halaman pembayaran. Parameter mesti dihantar sebagai objek berformat JSON.

Contoh:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (diperlukan secara bersyarat) Tujuan pembayaran untuk pembayaran berasaskan token. Nilai yang dibenarkan:

• recurring — untuk pembayaran berulang dengan jadual tetap.
• card_on_file — untuk pembayaran sekali atau tidak tetap, contohnya, mengecas pelanggan selepas perkhidmatan diberikan.

Contoh pautan pembayaran:

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

Sebelum menetapkan nilai kepada payment_sum, anda boleh menentukan pembolehubah pilihan tambahan untuk menyesuaikan pembayaran.

Secara lalai, mata wang pembayaran adalah Ruble Belarus (BYN). Jika anda ingin menggunakan mata wang lain, tetapkan nilai kepada pembolehubah currency.

Selepas pembayaran selesai, pembolehubah bepaid_callback_data ditambahkan kepada pelanggan. Ia mengandungi respons sistem pembayaran untuk transaksi yang telah selesai.

Anda boleh mendapatkan nilai yang diperlukan daripada kamus ini menggunakan fungsi get().

Cara Menguji Pembayaran

Untuk melakukan pembayaran ujian, tetapkan sebarang nilai kepada pembolehubah test_payments sebelum menetapkan pembolehubah payment_sum.

Penting: Alih keluar pembolehubah test_payments sebelum menukar bot anda ke mod langsung.

Kad Ujian

Nombor Kad Keputusan
4200000000000000 Pembayaran berjaya
4005550000000019 Pembayaran gagal

Contoh Menjana Pautan Pembayaran

Contoh berikut menjana pautan pembayaran untuk 100 ruble Belarus (mata wang lalai).

Nota: Mula-mula tetapkan sebarang pembolehubah konfigurasi tambahan, kemudian tetapkan nilai kepada payment_sum. Pembolehubah ini juga boleh ditetapkan lebih awal dalam aliran kerja anda—ia tidak semestinya berada dalam blok yang sama.

Akhir sekali, paparkan pembolehubah bepaid_pay_url di mana diperlukan. Ia mengandungi pautan pembayaran yang dijana.

Pengurusan Langganan

Integrasi bePaid membolehkan anda mencipta langganan untuk pelanggan anda.

Sebelum menggunakan fungsi ini di MaviBot, cipta pelan langganan dalam akaun bePaid anda.

Jika bahagian Pelan dan Langganan tidak tersedia dalam akaun anda, hubungi pengurus akaun anda.

Mencipta Langganan dan Menjana Pautan Pembayaran

Gunakan fungsi get_bepaid_subscription_url dan hantar parameter plan_id.

Fungsi ini mencipta langganan dan mengembalikan pautan pembayaran.

Hantar pautan yang dijana kepada pelanggan dan tunggu pembayaran selesai.

Selepas pembayaran berjaya:

  • langganan diaktifkan;
  • urusan menerima pembolehubah:
    • bepaid_subscription_id;
    • bepaid_subscription_status;
  • panggil balik dihantar ke bot (lihat Cara Mengendalikan Keputusan).

Mendapatkan Maklumat Langganan

Untuk mendapatkan maklumat langganan semasa, gunakan fungsi get_bepaid_subscription_info.

Hantar parameter subscription_id. Nilainya boleh diambil daripada pembolehubah bepaid_subscription_id.

Membatalkan Langganan

Untuk membatalkan langganan, gunakan fungsi cancel_bepaid_subscription.

Fungsi ini menerima satu parameter:

  • subscription_id — nilai boleh diambil daripada pembolehubah bepaid_subscription_id.

Selepas pembatalan berjaya:

  • pembolehubah bepaid_subscription_status ditetapkan kepada "canceled";
  • panggil balik dihantar ke bot (lihat Cara Mengendalikan Keputusan).

Status Langganan

Status Penerangan
trial Langganan tempoh percubaan aktif atau dibatalkan.
active Langganan aktif dengan pembayaran dibuat tepat pada masanya.
failed Langganan gagal. bePaid tidak dapat memproses pembayaran seterusnya.
error Ralat berlaku semasa bePaid cuba memproses pembayaran.
canceled Langganan telah dibatalkan dan tidak lagi aktif.

Pembayaran Berulang

Anda juga boleh menyediakan pembayaran berulang tanpa mencipta pelan langganan dalam akaun bePaid anda.

Untuk berbuat demikian, anda memerlukan token kad pelanggan.

Mendapatkan Token Kad

Untuk mendapatkan token kad pelanggan, pelanggan mesti melengkapkan pembayaran awal menggunakan pautan pembayaran yang dijana dengan pembolehubah payment_sum.

Sebelum menetapkan nilai kepada payment_sum, tetapkan pembolehubah bepaid_contract untuk menentukan tujuan pembayaran berasaskan token pada masa hadapan.

Nilai yang disokong:

  • recurring — untuk pembayaran berulang dengan jadual yang telah ditetapkan.
  • card_on_file — untuk pembayaran sekali atau tidak tetap, contohnya, mengecas pelanggan selepas perkhidmatan diberikan.

Nota: Pilihan card_on_file tidak disokong oleh semua bank pemerolehan. Hubungi pengurus akaun anda jika anda bercadang untuk menggunakan pilihan ini.

Selepas pembayaran berjaya, pembolehubah bepaid_client_card_token ditambahkan pada urusan. Ia menyimpan token kad pelanggan, yang boleh digunakan untuk pembayaran masa hadapan tanpa interaksi pelanggan.

Seterusnya, konfigurasikan aliran kerja anda, tentukan tarikh atau syarat yang diperlukan untuk mengecas pelanggan, dan panggil fungsi make_bepaid_token_payment.

Parameter mesti dihantar dalam susunan berikut:

amount → currency → description → contract

Penerangan Parameter

Nilai parameter contract mesti sepadan dengan tepat dengan nilai yang dinyatakan semasa menjana pautan pembayaran awal.

Parameter Penerangan
amount (diperlukan) Jumlah pembayaran. Nilai mestilah integer atau nombor perpuluhan, contohnya: 100 atau 100.5.
currency (diperlukan) Mata wang pembayaran dalam format ISO 4217, contohnya: USD.
description (diperlukan) Penerangan pembayaran, contohnya: "Pembayaran langganan mingguan untuk penyertaan dalam kelab hobi".
contract (diperlukan) Tujuan pembayaran mengikut token. Nilai yang dibenarkan: recurring atau card_on_file.

Jika pembayaran berjaya:

  • fungsi mengembalikan mesej "Caj berjaya melalui token bePaid";
  • bot menerima panggil balik pembayaran berjaya;
  • pembolehubah bepaid_token_payment_completed ditetapkan kepada True.

Jika pembayaran gagal:

  • fungsi mengembalikan mesej yang menerangkan sebab kegagalan;
  • bot menerima panggil balik dengan akhiran _fail;
  • pembolehubah bepaid_token_payment_completed ditetapkan kepada False.

Jika bank memerlukan pengesahan pelanggan tambahan, fungsi mengembalikan pautan di mana pelanggan boleh melengkapkan pengesahan 3-D Secure.

Cara Mengendalikan Keputusan

Sebagai respons kepada tindakan pelanggan, bot menerima panggil balik yang terdiri daripada 20 aksara pertama kunci rahsia diikuti dengan akhiran yang menunjukkan jenis operasi dan keputusan.

Panggil balik muncul dalam sistem sebagai mesej pengguna, tetapi ia tidak kelihatan kepada pelanggan.

Panggil Balik Pembayaran

Untuk pembayaran sekali, bot menerima salah satu panggil balik berikut:

  • keyNumber_success — pembayaran berjaya.
  • keyNumber_fail — pembayaran gagal.

Anda juga boleh menjejaki keputusan pembayaran menggunakan pembolehubah berikut:

  • bepaid_payment_completed — pembayaran selesai oleh pelanggan.
  • bepaid_token_payment_completed — pembayaran automatik selesai menggunakan token kad pelanggan.

Panggil Balik Langganan

Selepas langganan berjaya diaktifkan, sama ada semasa pembayaran awal atau pembayaran berulang, bot menerima:

keyNumber_success

Jika langganan dibatalkan, bot menerima:

keyNumber_canceled

Jika pembayaran langganan gagal, bot menerima:

keyNumber_fail