VAI Pay (JTL-Shop 5)

Owned by Kristian Stantschew (Unlicensed)
Last updated: Jul 04, 2023 by Sebastian Meyer
12 min read

Einleitung

Dieses Plugin integriert VAI Pay als Zahlungsart in Ihren JTL-Shop.

Die VAI Trade GmbH bietet im B2B-Bereich eine Rechnungskauflösung an, mit der Händler Ware von ihren
Lieferanten per Rechnung kaufen und in Raten bezahlen können. Dabei tritt die VAI Trade gegenüber dem
Lieferanten als Kunde auf, der auf Rechnung kauft und verkauft die Waren entsprechend an den Händler weiter. Der Lieferant bekommt die Zahlung für seine Waren innerhalb von 24 Stunden ausgezahlt und trägt so kein Risiko.

Anmerkung: Um die Begrifflichkeiten eindeutig zu verwenden, wird der Lieferant im Folgenden als „Verkäufer“ (da er den Online-Shop betreibt) und der kaufende Händler als „Käufer“ oder „Kunde“ (im Online-Shop) bezeichnet.

Weitere Informationen zu dem Thema finden sie hier:

https://support.vaitrade.de/de-form/articles/2104656-wie-funktioniert-einkaufsfinanzierung

Features

Frontend

  • Zahlungsart VAI Pay

Backend

  • Übersicht der Zahlungen mit VAI-Pay

  • Konfigurationshilfe zum Plugin

Wawi

  • Wawi-Workflows

Installation / Update

Systemvoraussetzungen

  • JTL-Shop 5.00+ und dessen Voraussetzungen

Weitere Voraussetzungen

Sie benötigen ein Kundenkonto, registrieren Sie sich unter: https://vaitrade.de/de/b2b.

Informieren Sie sich hier https://support.vaitrade.de/de-form/articles/2032365-welche-voraussetzungen-gibt-es über die weiteren Voraussetzungen von VAI Pay.

Plugin-Installation

Die Installation des Plugins erfolgt nach JTL-Standard, wie es hier beschrieben ist.

Plugin-Update

Bei einem Update auf eine neuere Version können Sie unter dem Menüpunkt “PLUGINS → Meine Käufe > Gebundene Lizenzen → VAI Pay” die Aktualisierung des Plugins auf die nächst verfügbare Version starten. In der Spalte Status klicken Sie auf “Aktualisieren“.

Konfiguration

Shop

Das Plugin unterstützt Sie bei der Einrichtung der Zahlungsart, wählen Sie dafür den Reiter “Hilfe“ im Plugin aus. Sie erhalten dort eine Übersicht über die Konfiguration. Überprüfen Sie an der Stelle die von Ihnen hinterlegten Einstellungen zu den Zahlungs- und Versandarten.

Zahlungsarten

Die Konfiguration der Zahlungsart erfolgt über die Standard-Verwaltung im JTL-Shop. Sie finden die Zahlungsarten unter Administration → Zahlungsarten. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins. Wählen Sie VAI Pay über das Stift-Symbol aus und konfigurieren Sie die Zahlungsmethode bei Bedarf.

Neben den Standard-Einstellungen für Zahlungsarten befinden sich im Plugin unter dem Tab Einstellungen die Einstellungen zur Zahlungsart. Hier können Sie die für den Betrieb im Plugin notwendigen Daten hinterlegen, welche Sie von VAI Pay für die Einrichtung erhalten haben.

Ist die Zahlungsart VAI Pay ausgewählt, dann wird der “Zahlungspflichtig bestellen”-Button mit einem im VAI-Design gehaltenen Zahlungsbutton ersetzt. Sie können aus drei verschiedenen Buttontexten wählen.

An welcher Stelle und mit welcher Methode der Button eingebunden wird bestimmen Sie über den Selektor und Selektor-Methode.

Option

Werte

Beschreibung

Option

Werte

Beschreibung

Aktiv:

Ja / Nein

Hier können Sie das Plugin global aktivieren oder deaktivieren.

API-Key (Live):

 

Geben Sie hier den Live API-Key ein, den Sie von VAI Pay nach Ihrer Registrierung erhalten haben. Dieser dient als Zugangsschlüssel für die Kommunikation mit VAI Pay.

Secret-Key (Live):

 

Geben Sie hier den Live Geheimschlüssel für die Kommunikation mit VAI Pay ein. Diesen haben sie ebenfalls nach Ihrer Registrierung bei VAI Pay erhalten. Dieser dient dazu die Kommunikation mit VAI Pay abzusichern.

API-Key (Sandbox):

 

Wenn sich Live und Sandbox API-Key nicht unterscheiden, geben Sie hier ebenfalls den Live API-Key für die Sandbox Kommunikation ein.

Secret-Key (Sandbox):

 

Wenn sich Live und Sandbox Secret-Key nicht unterscheiden, geben Sie hier ebenfalls den Live API-Key für die Sandbox Kommunikation ein.

Modus:

Sandbox / Live

Wählen Sie hier den Betriebsmodus aus

Sandbox - das Plugin kommuniziert mit der Testumgebung
Live - das Plugin akzeptiert reelle Zahlungen.

Farbschema:

Hell / Dunkel

Wählen Sie hier das Farbschema für den Bezahl-Button aus.

Button-Text:

“Bezahlen mit VAI”
“Jetzt einkaufen, später bezahlen“
“Ihr Einkauf in 4 Raten“

Wählen Sie Ihren favorisierten Button-Text. Der Text wird im VAI Pay Button angezeigt.

Button Selektor (Anzeigen):

CSS - Selektor

Standard: #complete-order-button

Geben Sie die CSS-Selektoren (komma-getrennt) an, an denen der Button gebunden werden soll. Ist nichts angegeben, dann wird der Standard-Selektor verwendet.

Button Selektor-Methode:

after - nach

before - davor

append - anhängen

prepend - voranstellen

replaceWith - ersetzen

after - der Button wird nach dem angebenden Element angefügt

before - der Button wird vor dem angebenden Element angefügt

append - der Button wird an das angebende Element angehängt

prepend der Button wird an das angebende Element vorangestellt

replaceWith - das angegebene Element wird mit dem Button ersetzt

Element Selektor (Entfernen):

 

Geben Sie hier die CSS Selektoren der Elemente an, welche ausgeblendet werden sollen. Im Standard wird stets das Element “#complete-order-button“ ausgeblendet. Wenn ihre ID des Buttons anders bezeichnet ist, dann können Sie hier ihren eigenen Selektor angeben.

Versandarten

Weisen Sie nun VAI Pay den gewünschten Versandarten/Ländern unter Administration → Versand zu. Das Plugin berücksichtigt auch etwaige Aufschläge zur Zahlungsmethode. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins.

JTL-Wawi

Damit die über VAI Pay getätigten Zahlungen in der JTL-Wawi den Bestellungen zugeordnet werden können, sind hierfür erweiterte Einstellungen vorzunehmen. Für eine korrekte Funktion mit VAI Pay sind die beschriebenen JTL-Workflows von besonderer Bedeutung, weitere Informationen hierzu finden sie hier: https://support.vaitrade.de/de-form/articles/3482535-welche-informationen-mussen-auf-meiner-rechnung-vorhanden-sein.

Zahlungsart einrichten WAWI 1.6

Öffnen Sie in der JTL-WAWI die Zahlungsartenverwaltung über Zahlungen → Zahlungsarten.

Legen Sie als Zahlungsart “VAI Pay” an. Beachten Sie, dass die Zahlungsarten dem “Angezeigten Namen“ im JTL-Shop entsprechen müssen.

Eigenes Feld anlegen

Öffnen Sie in der JTL-WAWI die Verwaltung Eigener Felder über Admin→ “Eigene Felder”.

Falls ein Update von v1.5 auf v1.6 durchgeführt wurde, dann finden Sie hier die VaiDealNumber unter “Automatisch generiert”. Sie können eine neue Gruppe “VAI Pay” erstellen und die VaiDealNumber in die Gruppe reinziehen, um Ihre Felder zu strukturieren:

 

Legen sie ansonsten ein neues Feld an mit der Bezeichnung “VaiDealNumber” und dem Datentyp “Kurztext”:

Die VaiDealNumber wird dann im Angebot/Auftrag rechts in der Übersicht unter “Eigene Felder” angezeigt:

Zahlungsart einrichten WAWI 1.5

Öffnen Sie in der JTL-WAWI die Zahlungsartenverwaltung über Zahlungen → Zahlungsarten.

Legen Sie als Zahlungsart “VAI Pay” an. Beachten Sie, dass die Zahlungsarten dem “Angezeigten Namen“ im JTL-Shop entsprechen müssen.

Bestellattribut anlegen

Wechseln Sie zu Verkauf (F6) und öffnen Sie einen Auftrag. Öffnen Sie die Auftragsattribute mit

und legen Sie das Attribut “VaiDealNumber“ an. Nun wird die übermittelte dealNumber angezeigt:

JTL-Workflow einrichten

Die VAI Trade GmbH tritt gegenüber dem Verkäufer als Käufer auf, somit darf die Rechnung anders als bei anderen Bestellungen nicht an den Käufer adressiert sein, sondern muss stattdessen an die VAI Trade GmbH gestellt werden.

Richten Sie einen WAWI-Workflow ein, um bei Anlage eines Auftrags mit VAI Pay als Zahlungsart automatisch die Rechnungsadresse des Auftrags auf die zu definierende Rechnungsadresse von VAI Trade zu ändern. Dabei gehen Sie wie folgt vor:

  1. Richten Sie “VAI Pay” als Zahlungsart ein.

  2. Öffnen Sie unter Admin >JTL-Workflows:

     

  3. Wählen Sie Aufträge:

     

    und markieren Sie “Komplett bezahlt”

  4. Legen Sie einen Workflow an mit:

     

  5. Bedingungen festlegen:

    Definieren Sie für die zuvor angelegte Zahlungsart “VAI Pay“, dass Zahlungen bearbeitet werden sollen.

  6. Aktionen festlegen:

    In Tabelle Rechnungsadressdaten sind alle zu ändernden Variablen aufgeführt.

    1. Wählen Sie die Aktion “Werte setzen“

    2. Bestimmen Sie mit Variable welches Datum geändert werden soll für
      Auftrag > Zahlungen > Rechnungsadresse > Variable

    3. Tragen Sie unter Wert den neuen Inhalt ein.

    4. Option “Feld leeren” steht leider nicht zu Verfügung, um eine Variable zu leeren fügen Sie bitte als Workaround ein “-“ (Minus) ein.

  7. Workflow testen

  8. Speichern Sie den Workflow

Rechnungsadressdaten

Die Einrichtungshilfe soll Sie dabei unterstützen, alle erforderlichen Variablen einzutragen.

Variable

Inhalt

Kommentar

Einrichtungshilfe

Variable

Inhalt

Kommentar

Einrichtungshilfe

Adresszusatz

-

 

erledigt

Anrede

-

 

erledigt

Bundesland

-

 

erledigt

EMail

vaipay@vaitrade.de

 

erledigt

Fax

-

 

erledigt

Firma

VAI Trade GmbH

 

erledigt

Firmenzusatz

-

 

LandISO

DE

 

Landname

Deutschland

 

Mobil

-

 

Name

-

 

Ort

Berlin

 

PLZ

10245

 

Straße

Warschauer Platz 11-13

 

Telefon

+49 30 9599984 20

 

Titel

-

 

Vorname

-

 

ZuHänden

-

bis Wawi 1.5

Tabelle: Rechnungsadressdaten

Das Feld “ZuHänden” gibt es ab Wawi 1.6 nicht mehr und der Workflow sollte das Datum nach Update nicht weiter beinhalten.

Umsatzsteuer ID

Sollten sie eine Umsatzsteuer ID auf der Rechnung ausweisen, so muss auch die Umsatzsteuer ID von VAI mit auf der Rechnung stehen. Sie können im einfachsten Fall die Umsatzsteuer ID in das Feld Firmenzusatz übernehmen:

WAWI-Workflow testen

  1. Testen Sie nun den Wawi-Workflow an einer Testbestellung, indem Sie zuerst eine Testbestellung in Ihrem Shop anlegen (Barzahlung o. Ä) und diese in die WAWI übertragen. Setzen Sie für die Bestellung die Zahlung über “VAI Pay“ und einem Zahlungseingang. Notieren Sie sich die Auftragsnummer (z.B. 123).

     

  2. Wechseln Sie zu JTL-Workflows in Aufträge > Komplett bezahlt > “Auftrag_Komplett bezahlt”

  3. Ihre Aktionen des Workflows sollten in etwa so aussehen:

     

  4. Starten Sie den Test mit

     

  5. Wählen Sie ein Objekt aus indem Sie nach Auftragsnummer suchen (z.B. 123)

     

  6. Öffnen Sie erneut den Auftrag. Der Rechnungsempfänger wurde geändert:

E-Mail-Vorlage anpassen

Sie als Verkäufer müssen dem Zwischenhändler die Rechnung des Käufers übersenden. Hierfür muss in diesem Fall eine Unterscheidung nach Zahlungsart in der E-Mail-Vorlage eingerichtet werden. Die korrekte E-Mail Adresse für den Vorgang wurde schon durch den Workflow gesetzt. Im Zahlungseingang zum Vorgang wurde die entsprechende DealNumber zugewiesen. Öffnen Sie Admin → “Druck- / E-Mail- / Exportvorlagen“

Wählen Sie Mailen → Standardvorlage → Bearbeiten. Es öffnet sich “E-Mail-Vorlagen bearbeiten”. Stellen Sie den Betreff auf “Benutzerdefiniert”, um die erweiterten Einstellungen “…“ öffnen zu können. Achten Sie darauf, dass auf der rechten Seite das Variablenset beginnend mit Vorgang verfügbar ist. Ist das nicht der Fall, dann benutzen sie eine neue Standardvorlage. Für den Betrieb ist die Vorlage “Standard (Veraltet)” zu verwenden, diese Vorlage enthält auch das benötigte Variablenset:

Betreff anpassen

Sofern Sie keine Anpassungen an Ihrer Standard E-Mai-Vorlage gemacht haben, können Sie den Code so übernehmen. Anderenfalls passen Sie den Code an bzw. fügen Ihre Änderungen in den ELSE-Teil ein:

{% if Vorgang.Zahlungen.ErstesObjekt.Zahlungsart.Name == "VAI Pay" %} Rechnung zu VAI-Deal: #{{ Vorgang.Zahlungen.ErstesObjekt.ExterneTransaktionsID }} {% else %} Rechnung über "{{ Report.InvoicePosition[0].Name | Truncate: 20 }}"{% case Report.InvoicePosition.Size %}{% when 0%}{% when 1 %}{% when 2 %} und einem weiteren Artikel{% else %} und {{ Report.InvoicePosition.Size | Minus: 1 }} weiteren Artikeln{% endcase%} von {{ Report.Company.CompanyName }} {% endif %}

Wawi 1.5

{% if Vorgang.Zahlungen.ErstesObjekt.Zahlungsart.Name == "VAI Pay" %} Rechnung zu VAI-Deal: #{% assign Attribute = Vorgang.Auftrag.Attribute | Split: '|' %}{% for Attribut in Attribute %}{% if Attribut contains 'VaiDealNumber' %}{{ Attribut | ReplaceFirst: 'VaiDealNumber=','' }}{% endif %}{% endfor %} {% else %} Rechnung über "{{ Report.InvoicePosition[0].Name | Truncate: 20 }}"{% case Report.InvoicePosition.Size %}{% when 0%}{% when 1 %}{% when 2 %} und einem weiteren Artikel{% else %} und {{ Report.InvoicePosition.Size | Minus: 1 }} weiteren Artikeln{% endcase%} von {{ Report.Company.CompanyName }} {% endif %}

Wawi 1.6

Rechnungs-PDF Name anpassen

Gleiches gilt auch für die Benennung des PDF-Rechnungsnamen. Fügen Sie Ihre Anpassungen hier auch in den ELSE-Teil weiter am Ende der Code-Zeile ein:

{% if Vorgang.Zahlungen.ErstesObjekt.Zahlungsart.Name == "VAI Pay" %}#{{ Vorgang.Zahlungen.ErstesObjekt.ExterneTransaktionsID }}.pdf{% else %}Rechnung-{{ Vorgang.Rechnungsnummer }}.pdf{% endif %}

Wawi 1.5

Wawi 1.6

Betrieb

Shop

Die Zahlungsart ist im Storefront des Shops wie eine reguläre JTL-Shop-Zahlungsart integriert.

Frontend

Die Zahlungsart VAI Pay steht Käufern nur unter bestimmten Voraussetzungen zur Verfügung. Die Zahlungsart kann nur für B2B in Deutschland und nur in Euro angeboten werden.

Ist das Rechnungsland nicht Deutschland, dann wird VAI Pay als Zahlungsart nicht angeboten.

Ist im Shop eine andere Währung als Euro ausgewählt, dann kann VAI Pay als Zahlungsart nicht angeboten werden.

Hat der Käufer keine Firma in den Kundenstammdaten eingetragen,, dann wird VAI Pay als Zahlungsart nicht angeboten.

Backend

Im Plugin-Backend können Sie die Bestellungen einsehen, die mit VAI Pay bezahlt wurden. Die Suche unterstützt Sie dabei die gewünschten Bestellungen zu finden.

Spalte

Beschreibung

Spalte

Beschreibung

Bestellnummer

Die Bestellnummer im JTL-Shop

Kunde

Name des Käufers/Kunden

Rechnungsnummer

Interne Rechnungsnummer (vom Plugin generierte UUID)

Deal-Nummer

VAI Pay Deal-Nummer (von VAI Pay generierte interne ID)

Status
(confimed / unconfirmed)

Status der Zahlung (bestätigt/unbestätigt)

Der Status ist bestätigt, wenn die Bestellung im JTL-Shop angelegt wurde und VAI Pay die übermittelten Beträge bestätigt hat.

Gesamtsumme

Gesamtsumme brutto im JTL-Shop (durch etwaige Gebühren können die Beträge im VAI Kundenaccount abweichen)

Bestelldatum

Zeitstempel der Bestellung bzw. Zahlung

IP-Adresse

IP des Käufers/Kunden

WAWI

Die JTL-Workflows, einmal eingerichtet, starten beim Wawi-Abgleich automatisch und bedürfen keiner weiteren Bearbeitung im Betrieb.

Das Plugin hat auch keine weiteren Interaktionen mit der Wawi, Stornos müssen direkt mit VAI geklärt werden. Weiterhin reagiert das Plugin auch umgekehrt nicht auf einen Wawi-Abgleich.

Individualisierung

Die Zahlungsart selbst hat keine individualisierbaren Elemente. Sie können allerdings bestimmen welches Farbschema und Button-Text auf der Zusammenfassungsseite angezeigt werden soll.

Wenn Sie ein eigenes Template verwenden, tragen Sie ihren speziellen Selektor für den “Zahlungspflichtig bestellen”-Button unter Button-Selektor (Anzeigen) ein.

Troubleshooting

Sollten Sie Probleme mit dem Plugin beobachten, prüfen Sie zunächst die Logs und wenden Sie sich ggf. an unseren Support oder Ihren Service-Partner, wenn Sie das Problem nicht selbständig lösen können.

Je mehr Informationen Sie dem Support bei einem Problem geben können, desto eher sind wir in der Lage, Ihnen zu helfen. Nicht reproduzierbare Probleme sind dagegen auch nur schwer zu analysieren.

Meldungen

Diese Meldung wird angezeigt, wenn der Käufer auf der Zusammenfassungsseite die andere Währung als Euro umgestellt hat und die Bestellung abschließen möchte. Er wird auf die Versand- und Zahlungsartseite zurückgeleitet und kann eine passend zur gewünschten Währung Zahlungsart auszuwählen.

 

Diese Meldung wird angezeigt, wenn der Kunde im VAI Pay Account auf “Abbrechen“ klickt und damit abbricht ohne den Auftrag einzureichen.

 

Diese Meldung wird angezeigt, wenn die von VAI Pay übermittelten Daten nicht mit dem Geheimschlüssel decodiert werden konnten.

 

Diese Meldung wird angezeigt, wenn die von VAI Pay übermittelten Daten nicht mit den aktuellen Daten in der Session übereinstimmen.

 

Diese Meldung wird angezeigt, wenn ein Fehler in der API-Kommunikation aufgetreten ist. In diesem Fall konnte VAI nicht endgültig die Echtheit der übermittelten Daten bestätigen. Die Bestellung konnte allerdings erfolgreich im JTL-Shop angelegt werden. Der Käufer wurde auf die Bestellbestätigungsseite geleitet.

 

Logs prüfen

Im Plugin-Backend werden dem Händler zu jeder Aktion Erfolgs- und Fehlermeldungen angezeigt. Das Plugin loggt prinzipiell sämtliche Aktionen ins Shop-Log (Debug-Level). Alle entsprechenden Meldungen können bequem mit dem Präfix “VAIPAY>“ gefiltert werden.

Um herauszufinden, wo ein Problem liegt, helfen Ihnen und uns die Logs. Je nach Fehlerbild ist eines der folgenden 3 Logs dafür mehr oder weniger relevant.

Browser-Log

Das Browser-Log ist meist relevant, wenn irgendwas im Frontend des Shops sich merkwürdig verhält oder nicht reagiert. (Beispiel: Sie klicken einen Button und augenscheinlich passiert gar nichts.)

Das Browser-Log sehen Sie, wenn Sie im Browser F12 drücken und dort dann auf Konsole (oder Console) wechseln.

Shop-Log

Das Shop-Log ist immer dann interessant, wenn im Frontend unerwartete Fehlermeldungen ausgegeben werden oder das Plugin zwar auf Eingaben im Frontend reagiert, aber nicht das Ergebnis liefert, was erwartet wurde. Manchmal ergibt sich auch durch das Browser-Log, dass die Informationen eher im Shop-Log zu suchen sind.

Das Shop-Log finden Sie im JTL-Adminbereich unter System → Wartung → Log.

Webserver-Log

Das Webserver-Log wird dann relevant, wenn Sie irgendwo auf einen Error 500 (= weiße Seite) stoßen.

Das Webserver-Log kann Ihnen Ihr Hoster zur Verfügung stellen.

Changelog

v1.0.3 (Juli 2023)

  • Bugfix: Verbesserte Prüfung von VAI Fehlerstatus bei fehlgeschlagenen Zahlungen

v1.0.2 (Februar 2023)

  • Übermittlung der Shop Bestellnummer

v1.0.1 (Januar 2023)

  • JTL Shop 5.2 Kompatibilität

v1.0.0 (August 2022)

  • Initiales Release

Support und Kontakt

siehe Support und Kontakt