So verbinden Sie sich

Um das bePaid-Zahlungssystem zu verbinden, benötigen Sie eine Store-ID, einen geheimen Schlüssel und einen öffentlichen Schlüssel. Sobald Sie diese Anmeldeinformationen erhalten haben, fahren Sie mit den Zahlungssystemeinstellungen in MaviBot fort.

Um die Store-ID, den geheimen Schlüssel und den öffentlichen Schlüssel zu erhalten, wenden Sie sich an den bePaid-Technischen Support.

Öffnen Sie in MaviBot den Abschnitt Acquiring, wählen Sie bePaid aus und geben Sie die erhaltenen Anmeldeinformationen ein.

Hinweis: Das letzte Feld ist ein Schalter, der den API-Endpunkt je nach Nutzungsland auswählt: Weißrussland oder Russland.

Um einen Zahlungslink zu generieren, weisen Sie der Variablen payment_sum einen Wert zu (z. B.: 150 oder 100.55; verwenden Sie einen Punkt als Dezimaltrennzeichen).

Sobald die Variable payment_sum gesetzt ist, wird die Variable bepaid_pay_url automatisch erstellt. Sie können diese Variable als Link in einer Nachricht anzeigen oder in einer Schaltfläche mit dem Text "Bezahlen" verwenden.

Funktionsparameter Beschreibung Weitere Informationen
currency Zahlungswährung im ISO 4217-Format. Zum Beispiel: USD
language Sprache der Zahlungsseite. Standard: en. Zulässige Werte:
• en — Englisch
• es — Spanisch
• tr — Türkisch
• de — Deutsch
• it — Italienisch
• ru — Russisch
• zh — Chinesisch
• fr — Französisch
• da — Dänisch
• sv — Schwedisch
• no — Norwegisch
• fi — Finnisch
• pl — Polnisch
• ja — Japanisch
• uk — Ukrainisch
• be — Weißrussisch
• ka — Georgisch
• ro — Rumänisch
payment_description Zahlungsbeschreibung. —
link_expired Ablauf des Zahlungslinks. Legen Sie das Ablaufdatum im Format dd.mm.yyyy fest (z. B.: 25.06.2025). Standardmäßig muss die Zahlung innerhalb von 24 Stunden abgeschlossen sein. Sie können auch das Feld Variablen bei Weiterleitung zuweisen verwenden:

• link_expired = current_date + 2 — der Link ist 2 Tage bis 00:00 Uhr gültig.

• Sie können ein genaues Ablaufdatum und eine genaue Uhrzeit im Format dd.mm.yyyy hh:mm angeben (z. B.: 25.06.2025 12:23).

Es können auch Standardvariablen verwendet werden. Beispiel für einen Link, der 30 Minuten gültig ist:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host Indikator für einen auf dem russischen bePaid-Host registrierten Shop. Setzen Sie diesen Parameter auf 1, wenn Ihr Shop auf bepaid.tech registriert ist. Um zum weißrussischen Host zu wechseln, setzen Sie diesen Parameter auf "" (leerer Wert).
test_payments Aktiviert Testzahlungen. Weisen Sie dieser Variablen vor dem Erstellen des Zahlungslinks einen beliebigen Wert zu. —
bepaid_attempts Gibt die Anzahl der Zahlungsversuche an. Standardmäßig ist 1 Versuch erlaubt. —
customer_data Ein JSON-Objekt, das first_name, last_name und email des Zahlers enthält. Diese Informationen sind erforderlich, um die Zahlungsquittung zu senden, und können auf der Zahlungsseite bearbeitet werden. Der Parameter muss als JSON-formatiertes Objekt übergeben werden.

Beispiel:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (bedingt erforderlich) Zahlungszweck für tokenbasierte Zahlungen. Zulässige Werte:

• recurring — für wiederkehrende Zahlungen mit einem festen Zeitplan.
• card_on_file — für einmalige oder unregelmäßige Zahlungen, z. B. Belastung des Kunden nach Erbringung einer Dienstleistung.

Beispiel für einen Zahlungslink:

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

Bevor Sie der Variable payment_sum einen Wert zuweisen, können Sie zusätzliche optionale Variablen definieren, um die Zahlung anzupassen.

Standardmäßig ist die Zahlungswährung der Weißrussische Rubel (BYN). Wenn Sie eine andere Währung verwenden möchten, weisen Sie der Variablen currency einen Wert zu.

Nach Abschluss der Zahlung wird dem Kunden die Variable bepaid_callback_data hinzugefügt. Sie enthält die Antwort des Zahlungssystems für die abgeschlossene Transaktion.

Sie können die erforderlichen Werte aus diesem Wörterbuch mit der Funktion get() abrufen.

So testen Sie Zahlungen

Um eine Testzahlung durchzuführen, weisen Sie der Variablen test_payments vor dem Setzen der Variable payment_sum einen beliebigen Wert zu.

Wichtig: Entfernen Sie die Variable test_payments, bevor Sie Ihren Bot in den Live-Modus schalten.

Testkarten

Kartennummer Ergebnis
4200000000000000 Erfolgreiche Zahlung
4005550000000019 Fehlgeschlagene Zahlung

Das folgende Beispiel generiert einen Zahlungslink für 100 Weißrussische Rubel (Standardwährung).

Hinweis: Weisen Sie zuerst alle zusätzlichen Konfigurationsvariablen zu, dann weisen Sie den Wert payment_sum zu. Diese Variablen können auch früher in Ihrem Workflow zugewiesen werden – sie müssen sich nicht im selben Block befinden.

Zeigen Sie abschließend die Variable bepaid_pay_url an der gewünschten Stelle an. Sie enthält den generierten Zahlungslink.

Abonnementverwaltung

Die bePaid-Integration ermöglicht es Ihnen, Abonnements für Ihre Kunden zu erstellen.

Bevor Sie diese Funktionalität in MaviBot nutzen, erstellen Sie einen Abonnementplan in Ihrem bePaid-Konto.

Wenn die Abschnitte Pläne und Abonnements in Ihrem Konto nicht verfügbar sind, wenden Sie sich an Ihren Account Manager.

Verwenden Sie die Funktion get_bepaid_subscription_url und übergeben Sie den Parameter plan_id.

Die Funktion erstellt ein Abonnement und gibt einen Zahlungslink zurück.

Senden Sie den generierten Link an den Kunden und warten Sie, bis die Zahlung abgeschlossen ist.

Nach einer erfolgreichen Zahlung:

  • wird das Abonnement aktiviert;
  • erhält der Deal die Variablen:
    • bepaid_subscription_id;
    • bepaid_subscription_status;
  • wird ein Callback an den Bot gesendet (siehe So verarbeiten Sie das Ergebnis).

Abrufen von Abonnementinformationen

Um die aktuellen Abonnementinformationen abzurufen, verwenden Sie die Funktion get_bepaid_subscription_info.

Übergeben Sie den Parameter subscription_id. Sein Wert kann der Variablen bepaid_subscription_id entnommen werden.

Kündigen eines Abonnements

Um ein Abonnement zu kündigen, verwenden Sie die Funktion cancel_bepaid_subscription.

Die Funktion akzeptiert einen einzelnen Parameter:

  • subscription_id — der Wert kann der Variablen bepaid_subscription_id entnommen werden.

Nach einer erfolgreichen Kündigung:

  • wird die Variable bepaid_subscription_status auf "canceled" gesetzt;
  • wird ein Callback an den Bot gesendet (siehe So verarbeiten Sie das Ergebnis).

Abonnementstatus

Status Beschreibung
trial Aktives oder gekündigtes Abonnement im Testzeitraum.
active Aktives Abonnement mit pünktlicher Zahlung.
failed Fehlgeschlagenes Abonnement. bePaid konnte die nächste Zahlung nicht verarbeiten.
error Bei dem Versuch von bePaid, die Zahlung zu verarbeiten, ist ein Fehler aufgetreten.
canceled Abonnement wurde gekündigt und ist nicht mehr aktiv.

Wiederkehrende Zahlungen

Sie können auch wiederkehrende Zahlungen einrichten, ohne einen Abonnementplan in Ihrem bePaid-Konto zu erstellen.

Dazu benötigen Sie das Kartentoken des Kunden.

Abrufen eines Kartentokens

Um das Kartentoken des Kunden zu erhalten, muss der Kunde eine erste Zahlung über einen mit der Variable payment_sum generierten Zahlungslink abschließen.

Bevor Sie payment_sum einen Wert zuweisen, setzen Sie die Variable bepaid_contract, um den Zweck zukünftiger tokenbasierter Zahlungen zu definieren.

Unterstützte Werte:

  • recurring — für wiederkehrende Zahlungen mit einem vordefinierten Zeitplan.
  • card_on_file — für einmalige oder unregelmäßige Zahlungen, z. B. Belastung des Kunden nach Erbringung einer Dienstleistung.

Hinweis: Die Option card_on_file wird nicht von allen Acquiring-Banken unterstützt. Wenden Sie sich an Ihren Account Manager, wenn Sie diese Option nutzen möchten.

Nach einer erfolgreichen Zahlung wird dem Deal die Variable bepaid_client_card_token hinzugefügt. Sie speichert das Kartentoken des Kunden, das für zukünftige Zahlungen ohne Kundeninteraktion verwendet werden kann.

Konfigurieren Sie als Nächstes Ihren Workflow, definieren Sie das erforderliche Datum oder die Bedingung für die Belastung des Kunden und rufen Sie die Funktion make_bepaid_token_payment auf.

Die Parameter müssen in der folgenden Reihenfolge übergeben werden:

amount → currency → description → contract

Parameterbeschreibungen

Der Wert des Parameters contract muss genau mit dem Wert übereinstimmen, der bei der Generierung des ersten Zahlungslinks angegeben wurde.

Parameter Beschreibung
amount (erforderlich) Zahlungsbetrag. Der Wert muss eine ganze Zahl oder eine Dezimalzahl sein, z. B.: 100 oder 100.5.
currency (erforderlich) Zahlungswährung im ISO 4217-Format, z. B.: USD.
description (erforderlich) Zahlungsbeschreibung, z. B.: "Wöchentliche Abonnementzahlung für die Teilnahme am Hobbyclub".
contract (erforderlich) Zahlungszweck per Token. Zulässige Werte: recurring oder card_on_file.

Wenn die Zahlung erfolgreich ist:

  • gibt die Funktion die Meldung "Erfolgreiche Belastung über bePaid-Token" zurück;
  • erhält der Bot einen erfolgreichen Zahlungs-Callback;
  • wird die Variable bepaid_token_payment_completed auf True gesetzt.

Wenn die Zahlung fehlschlägt:

  • gibt die Funktion eine Meldung zurück, die den Grund des Fehlschlags beschreibt;
  • erhält der Bot einen Callback mit dem Suffix _fail;
  • wird die Variable bepaid_token_payment_completed auf False gesetzt.

Wenn die Bank eine zusätzliche Kundenüberprüfung benötigt, gibt die Funktion einen Link zurück, über den der Kunde die 3-D Secure-Authentifizierung abschließen kann.

So verarbeiten Sie das Ergebnis

Als Reaktion auf Kundenaktionen erhält der Bot Callbacks, die aus den ersten 20 Zeichen des geheimen Schlüssels bestehen, gefolgt von einem Suffix, das den Vorgangstyp und das Ergebnis angibt.

Der Callback erscheint im System als Benutzernachricht, ist aber für den Kunden nicht sichtbar.

Zahlungs-Callbacks

Bei einmaligen Zahlungen erhält der Bot einen der folgenden Callbacks:

  • keyNumber_success — erfolgreiche Zahlung.
  • keyNumber_fail — fehlgeschlagene Zahlung.

Sie können das Zahlungsergebnis auch mit den folgenden Variablen verfolgen:

  • bepaid_payment_completed — Zahlung vom Kunden abgeschlossen.
  • bepaid_token_payment_completed — automatische Zahlung mit dem Kartentoken des Kunden abgeschlossen.

Abonnement-Callbacks

Nach erfolgreicher Aktivierung eines Abonnements, entweder bei der ersten Zahlung oder einer wiederkehrenden Zahlung, erhält der Bot:

keyNumber_success

Wenn das Abonnement gekündigt wird, erhält der Bot:

keyNumber_canceled

Wenn eine Abonnementzahlung fehlschlägt, erhält der Bot:

keyNumber_fail