Das Pay:Me App-to-App SDK

Karten Zahlungen per Terminal sind heute überall möglich. Leider sind die oft vorhandenen Lösungen von der Stange oft zu unflexibel oder es gibt im Unternehmensumfeld bereits eine Frontend App und es fehlt nur noch das Payment per Terminal.

Wir haben eine Schnittstelle geschaffen, die Ihre App einfach an die VR-pay:Me App „andockt“. So kann auf einfache Art und Weise Payment in Ihrer Applikation integriert werden.

Eine Zahlung über 5,00 Euro gelingt dann so einfach wie:

Quellcode unter Android:
RequestBuilder.payment(API_KEY, this)
.amount("5.00")
.start();
Quellcode unter iOS:
RequestBuilder.payment(authKey: API_KEY, callbackScheme: URL-SCHEMA)
.amount("5.00")
.start();

Der komplizierte Prozess wie die Kommunikation mit dem Payment-Terminal und der komplette Zahlungsprozess, wird Ihnen hiermit abgenommen. Wir geben Ihnen alles in die Hand um Zahlungen mit einem Terminal durchführen zu können.

Vorausetzungen zur Nutzung

Bitte stellen Sie kurz Ihr Unternehmen und Ihr Projekt vor, damit wir Ihnen den API Key zusenden können.

Weitere Features
  • Durchführung Payment mit diversen Optionen
    • Unterschiedliche Mehrwertsteuer Sätze
    • Trinkgeld Funktion
    • Belegversand per E-Mail
    • Rückantwort in Ihrer App, ob der Zahlungsvorgang erfolgreich war (ggf. Fehlermeldung)
  • Stornierung
  • Kassenschnitt
  • Synchronisierung von Zahlungen wenn Status nicht bekannt ist

Technische Informationen zum Einbauen des SDK in Apps

Als Referenz für die Dokumentation dienen die Beispiel-Apps.
Alle Code-Beispiele finden sich in der Beispiel-Apps wieder.

Voraussetzungen

Um das SDK einsetzen zu können, muss die App folgende Voraussetzungen erfüllen.

Für Android:
  • minSDK: > 21 (Android 5.0)
  • targetSDK: > 28 (Android 9.0)
  • VR-pay:Me App mindestens in Version > 1.4

Download der Android App siehe oben

Für iOS:
  • minimum SDK: > iOS 11
  • Xcode 11
  • Ausführung ist nur noch auf einem Gerät möglich
  • VR-pay:Me App mindestens in Version > 1.4

Download der iOS App siehe oben

Allgemeine Infos

Bevor eine externe App eine Transaktion durchführen kann, muss die VR-pay:Me App initial eingerichtet werden. Dies bedeutet es muss eine Bluetooth Verbindung mit dem Terminal hergestellt sein und in der VR-pay:Me App ausgewählt werden.

Wenn der Kundenbeleg über die App per E-Mail versendet werden soll, müssen hierfür die entsprechenden Daten in der VR-pay:Me App eingetragen werden.

Alle Transaktionen die von Extern durchgeführt werden, sind auch in der Transaktionsübersicht der VR-pay:Me App ersichtlich. Es wäre auch möglich nur Zahlungen über die externe Anwendung durchzuführen und z. B. Storno und Kassenschnitt über die VR-pay:Me App zu machen.

Android

 

Inhalt

 

Einbinden der App-To-App Library in die aufzurufende App

Zuerst legt man in der App ein neues Modul an.

Modul

Als Typ muss "AAR Package" ausgewählt werden.

Typ

Im nächsten Schritt wählt man die "vr-payme-android-sdk-2.1.0-prodRelease.aar" Datei aus dem ZIP File "vr-payme-android-sdk-2.1.0-prodRelease.aar.zip" und vergibt einen Namen für das Modul.

SDK

Sobald das Library-Modul angelegt wurde, kann es im gradle-Script des App-Moduls als Abhängigkeit referenziert werden:

dependencies {
        implementation project(path: ':vr-payme-android-sdk')
    }

 

Ablauf der Kommunikation

Das SDK kommuniziert mit der VR-pay:Me App über Intents. Beim Aufruf der execute() Methode muss die aufrufende Activity übergeben werden.

An diese Actvity wird das Ergebnis der Transaktion gesendet. Dazu muss in der Activity die Methode onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) überschrieben werden.

In dem SDK gibt es ebenfalls die Methode onActivityResult(requestCode: Int, resultCode: Int, data: Intent?), welche die Antwort der VR-pay:Me App in ein Ergebnis vom Typ ResultWrapper parst.

 

Autorisierung des SDKs

Bei jeder Ausführung einer Transaktion (Zahlung starten, Zahlung stornieren, Kassenschnitt durchführen, Transaktion synchronisieren) muss beim Aufruf des SDKs ein API-Key mitgesendet werden.

 

Starten einer Zahlung

Anfrage

Innerhalb einer Activity kann mit folgendem Quellcode die Zahlung durchgeführt werden:

try {
    RequestBuilder.payment(API_KEY, this)
        .amount(amount) // Betrag in Eurocents
        .tax(tax) // Steuersatz, z.B. 19
        .tip(tip) // Trinkgeld in Eurocents
        .cashier(cashier) // Name des Kassierers
        .email(email) // Email-Adresse an die der Beleg versendet werden soll
        .userReference(userReference) // Benutzerdefinierte Referenz
        .start()
    } catch (...) {
        // Fehlerbehandlung
        ...
    }
}
Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
userReference String Die Transaktions-Referenz, die vom Benutzer vergeben werden kann
2.1 1.7
tip Double Trinkgeldbetrag in Cent
1.0 1.4
tax Double Mehrwertsteuer in %

Es sind nur folgende gültige Werte gültig:
  • 0 %
  • 5,5 %
  • 7 %
  • 10,7 %
  • 19 %

1.0 1.4
  • 5 %
  • 16 %

2.0 1.6
email String E-Mail-Adresse für den Beleg
1.0 1.4
cashier String Name des Kassierers
1.0 1.4
amount Integer Betrag in Cent

Der zu zahlender Betrag inkl. Tip.
Dieser Betrag wird an das Terminal übermittelt
x 2.0 1.6


Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Zahlung automatisch ausgeführt. Sollte die App nicht installiert sein, wird die AppNotInstalledException geworfen.

Antwort

Sobald die Zahlung durchgeführt wurde, wird die VR-pay:Me App geschlossen und das Gerät springt in die aufrufende App zurück.

Dort wird die Methode onActivityResult aufgerufen:

val paymentResult = ResponseHandler.parsePaymentResult(requestCode, resultCode, data)

when (paymentResult.status) {
    PaymentResultStatus.SUCCESS -> TODO()
    PaymentResultStatus.FAILURE -> TODO()
    PaymentResultStatus.INVALID_INPUT -> TODO()
    PaymentResultStatus.NOT_READY -> TODO()
    PaymentResultStatus.NO_CONNECTION -> TODO()
    PaymentResultStatus.MAIL_NOT_SENT -> TODO()
    PaymentResultStatus.SIGNATURE_TIME_OUT -> TODO()
    PaymentResultStatus.APP_VERSION_TOO_LOW -> TODO()
    PaymentResultStatus.LIB_VERSION_TOO_LOW -> TODO()
}

Folgende Felder sind im Objekt PaymentResult vorhanden:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
amount Integer tatsächlicher Zahlbetrag in Cent x 1.0 1.4
status PaymentResultStatus Statuscode der Anfrage

0 => Erfolgreich
1 => Zahlung fehlgeschlagen
2 => Eingabe ungültig
3 => App nicht bereit
4 => Terminal nicht verbunden
5 => Mailversand nicht möglich
x 1.0 1.4
maskedPan String Maskierte PAN
1.0 1.4
customerReceipt String Kundenbeleg aus dem Terminal
1.0 1.4
cardBrand String Kartengesellschaft.
1.0 1.4
tax double Gewählter Mehrwertsteuersatz
1.0 1.4
userReference String Eingegebene Transaktions-Referenz
2.1 1.7
identifier String Die Transaktions-Referenz aus dem Terminal 
1.0 1.4
cardType String Die Eingabe-Methode der Karte.

Mögliche Werte:
01: Manuelle Eingabe
02: Magnetstreifen
05: Chipkarte
07: Kontaktlos

1.0 1.4


06: Timeout durch fehlende Signatur x 2.0 1.6

 

Stornieren einer Zahlung

Bitte beachten: Eine Transaktion kann nur bis zum nächsten Kassenschnitt storniert werden. Daher werden beim Kassenschnitt die identifier der übertragenen Zahlungen mit zurückgegeben.

Anfrage

Innerhalb einer Activity kann mit folgendem Quellcode die Zahlung storniert werden:

try {
    RequestBuilder.cancellation(API_KEY, this)
        .amount(amount)
        .identifier(identifier)
        .start()
    } catch (...) {
        // Fehlerbehandlung
        ...
    }
}
Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
amount Integer Betrag in Cent x 1.0 1.4
identifier String Die Referenz der zu stornierenden Transaktion aus dem Terminal x 1.0 1.4


Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Zahlung automatisch storniert. Sollte die App nicht installiert sein, wird die AppNotInstalledException geworfen.

Antwort

Sobald die Zahlung storniert wurde, wird die VR-pay:Me App geschlossen und das Gerät springt in die aufrufende App zurück.

Dort wird die Methode onActivityResult aufgerufen:

val cancellationResult = ResponseHandler.parseCancellationResult(requestCode, resultCode, data)

when (cancellationResult.status) {
    CancellationResultStatus.SUCCESS -> TODO()
    CancellationResultStatus.FAILURE -> TODO()
    CancellationResultStatus.INVALID_INPUT -> TODO()
    CancellationResultStatus.NOT_READY -> TODO()
    CancellationResultStatus.NO_CONNECTION -> TODO()
    CancellationResultStatus.APP_VERSION_TOO_LOW -> TODO()
    CancellationResultStatus.LIB_VERSION_TOO_LOW -> TODO()
}

Folgende Werte kann der resultStatus annehmen:

SUCCESS, // Vorgang erfolgreich
FAILURE, // Vorgang nicht erfolgreich
INVALID_INPUT, // Framework nicht korrekt aufgerufen (Kein Betrag
übergeben)
NOT_READY, // Die VR-Pay:me App ist nicht vollständig eingerichtet
NO_CONNECTION // Es ist aktuell kein Terminal verbunden
APP_VERSION_TOO_LOW // Siehe Abschnitt Versionierung
LIB_VERSION_TOO_LOW // Siehe Abschnitt Versionierung.

 

Kassenschnitt durchführen

Der Kassenschnitt muss durchgeführt werden damit die Zahlungen dem Konto gutgeschrieben werden.

Anfrage

Innerhalb einer Activity kann mit folgendem Quellcode der Kassenschnitt durchgeführt werden:

RequestBuilder.dataClearing(API_KEY, this).start()

Zum Starten des Kassenschnitts werden keine weiteren Daten benötigt.

Ist die VR-pay:Me App installiert, wird sie aufgerufen und der Kassenschnitt gestartet. Sollte die App nicht installiert sein, wird die AppNotInstalledException geworfen.

Antwort

Sobald der Kassenschnitt durchgeführt wurde, wird die VR-pay:Me App geschlossen und das Gerät springt in die aufrufende App zurück.

Dort wird die Methode onActivityResult aufgerufen:

val dataClearingResult = ResponseHandler.parseDataClearingResult(requestCode, resultCode, data)

when (dataClearingResult.status) {
    DataClearingResultStatus.SUCCESS -> TODO()
    DataClearingResultStatus.FAILURE -> TODO()
    DataClearingResultStatus.NOT_READY -> TODO()
    DataClearingResultStatus.NO_CONNECTION -> TODO()
    DataClearingResultStatus.APP_VERSION_TOO_LOW -> TODO()
    DataClearingResultStatus.LIB_VERSION_TOO_LOW -> TODO()
}

Folgende Felder sind im Objekt DataClearingResult vorhanden:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
status DataClearingResultStatus Statuscode der Anfrage x 1.0 1.4
receipt String Händlerbeleg für den Kassenschnitt
1.0 1.4
clearedIdentifier String-Array Identifier der Transkationen, die freigegeben wurden
1.0 1.4

 

Transaktion synchronisieren

Sollte der Status einer Transaktion nicht korrekt übertragen worden sein, kann mit der Funktion beginSync der Status der letzten Transkation abgerufen werden.

Anfrage

Innerhalb einer Activity kann mit folgendem Quellcode die Synchronisation durchgeführt werden:

try {
    RequestBuilder.sync(API_KEY, this).start()
    } catch (...) {
        // Fehlerbehandlung
    ...
}

Zum Starten der Synchronisierung werden keine weiteren Daten benötigt.

Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Synchronisierung gestartet. Sollte die App nicht installiert sein, wird die AppNotInstalledException geworfen.

Antwort

Sobald die Synchronisierung durchgeführt wurde, wird die VR-pay:Me App geschlossen und das Gerät springt in die aufrufende App zurück.

Dort wird die Methode onActivityResult aufgerufen:

val syncResult = ResponseHandler.parseSyncResult(requestCode, resultCode, data)

when(syncResult.status) {
    SyncResultStatus.NOT_READY -> TODO()
    SyncResultStatus.NO_CONNECTION -> TODO()
    SyncResultStatus.SYNC_OPERATION_FAILED -> TODO()
    SyncResultStatus.SYNC_OPERATION_SUCCEEDED -> {
        syncResult.paymentResult?.let {
            // Zahlungsdaten nutzen
            ...
        }
        syncResult.cancellationResult?.let {
            // Stornierungsdaten nutzen
            ...
        }
        syncResult.dataClearingResult?.let {
            // Kassenschnittdaten nutzen
            ...
        }
    }
    SyncResultStatus.APP_VERSION_TOO_LOW -> TODO()
    SyncResultStatus.LIB_VERSION_TOO_LOW -> TODO()
}

Da die Pending Transaction sowohl eine Zahlung, eine Stornierung oder ein Kassenschnitt sein kann, enthält das Objekt PendingTransaction alle Felder aus den drei Antworten:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
status SyncResultStatus Folgende Werte kann der Status annehmen:

NOT_READY, // Die VR-Pay:me App ist nicht vollständig eingerichtet
NO_CONNECTION, // Es ist aktuell kein Terminal verbunden
SYNC_OPERATION_FAILED // Vorgang nicht erfolgreich
SYNC_OPERATION_SUCCEEDED // Vorgang erfolgreich
APP_VERSION_TOO_LOW // Ab Lib Version 2.1
LIB_VERSION_TOO_LOW // Ab Lib Version 2.1
x 1.0 1.4
amount Integer tatsächlicher Zahlbetrag in Cent x 1.0 1.4
identifier String Die Transaktions-Referenz aus dem Terminal 
1.0 1.4
maskedPan String Maskierte PAN
1.0 1.4
cardType String Die Eingabe-Methode der Karte.

Mögliche Werte:
01: Manuelle Eingabe
02: Magnetstreifen
05: Chipkarte
07: Kontaktlos

1.0 1.4
cardBrand String Kartengesellschaft. Wird aus der IIN der Transaktion ermittelt.
1.0 1.4
tax double Gewählter Mehrwertsteuersatz
1.0 1.4
customerReceipt String Kundenbeleg aus dem Terminal
1.0 1.4
date Date Datum der Transaktion
1.0 1.4
clearedIdentifier String-Array Identifier der Transkationen, die freigegeben wurden
1.0 1.4

iOS

 

Inhalt

 

Einbinden der App-To-App Library in die aufzurufende App

Zum Einbinden des Frameworks muss die "VRPayme.framework" Datei per Drag&Drop aus dem Finder in das Projekt gezogen werden.

Im Dialog müssen die Schemes angehakt werden, für die das Framework verfügbar sein sollen. In diesem Fall ist es nur das Scheme "VRPaymeTestApp".

Schemes

Das Framework sollte nun in den Projekteinstellungen unter Frameworks, Libraries and Embedded Content aufgelistet sein.

Framework

Das SDK kommuniziert mit der VR-pay:Me App über Custom URL-Schemes. Die VR-pay:Me App wird von dem SDK über das Custom URL-Scheme aufgerufen.

Das Ergebnis der Transaktion wird ebenfalls über eine URL an die aufrufende App gesendet.

Dazu muss in der App unter Projekt → App-Target auswählen → Info ein URL Type registriert werden.

URL Type

Das registrierte URL Scheme muss bei jedem Aufruf an das SDK übergeben werden.

Sollte das Callback-Scheme nicht gesetzt sein, wird der Fehler RequestBuilderError.invalidCallbackScheme(1) geworfen.

Neben dem URL-Scheme muss beim Auruf des SDKs ein API-Key mitgesendet werden.

Sollte der API-Key nicht korrekt sein, wird der Fehler RequestBuilderError.invalidApiKey(0) geworfen.

 

Starten einer Zahlung

Anfrage

Innerhalb der App kann mit folgendem Quellcode die Zahlung durchgeführt werden:

var payment = RequestBuilder
    .payment(authKey: API_KEY, callbackScheme: URL-SCHEMA)
    .amount(amount) // Betrag in Eurocents
    .tip(tip) // Trinkgeld in Eurocents
    .cashier(cashier) // Name des Kassierers
    .tax(tax) // Steuersatz, z.B. 19
    .email(email) // Email-Adresse an die der Beleg versendet werden soll
    .userReference(userReference) // Benutzerdefinierte Referenz
 
try payment.start()
Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
userReference String Die Transaktions-Referenz, die vom Benutzer vergeben werden kann
2.1 1.7
tip Double Trinkgeldbetrag in Cent
1.0 1.4
tax Double Mehrwertsteuer in %

Es sind nur folgende gültige Werte gültig:
  • 0 %
  • 5,5 %
  • 7 %
  • 10,7 %
  • 19 %

1.0 1.4
  • 5 %
  • 16 %

2.0 1.6
email String E-Mail-Adresse für den Beleg
1.0 1.4
cashier String Name des Kassierers
1.0 1.4
amount Integer Betrag in Cent

Der zu zahlender Betrag inkl. Tip.
Dieser Betrag wird an das Terminal übermittelt
x 2.0 1.6


Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Zahlung automatisch ausgeführt. Sollte die App nicht installiert sein, wird der Fehler RequestBuilderError.missingVRPaymeApp(3) geworfen.

Antwort

Sobald die Zahlung durchgeführt wurde, wird die VR-pay:Me App geschlossen. Die aufrufende App wird über das oben angegebene Callback-Scheme aufgerufen.

Im AppDelegate wird daraufhin vom System die Methode

func application(_ app:
    UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey :
    Any] = [:])

aufgerufen. Darin kann mit folgendem Code die Antwort ausgewertet werden:

guard let payment = try? ResponseHandler.parsePaymentResult(url: url) else {
    // Das Objekt enthält keine Antwort des VRPayment Frameworks
    ...
}
 
switch payment.status {
    case .SUCCESS:
        // Zahlung wurde erfolgreich durchgeführt
        ...
    case .FAILURE:
        // Zahlung fehlgeschlagen
        ...
    case .SIGNATURE_TIME_OUT:
        // Zahlung wurde erfolgreich durchgeführt. Signatur wurde nicht eingegeben
        ...
    default:
        // Die Zahlung wurde nicht durchgeführt
        ...
    break
}

Folgende Felder sind im Objekt Payment vorhanden:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
amount Integer tatsächlicher Zahlbetrag in Cent x 1.0 1.4
status PaymentResultStatus Statuscode der Anfrage

0 => Erfolgreich
1 => Zahlung fehlgeschlagen
2 => Eingabe ungültig
3 => App nicht bereit
4 => Terminal nicht verbunden
5 => Mailversand nicht möglich
x 1.0 1.4
maskedPan String Maskierte PAN
1.0 1.4
customerReceipt String Kundenbeleg aus dem Terminal
1.0 1.4
cardBrand String Kartengesellschaft.
1.0 1.4
tax double Gewählter Mehrwertsteuersatz
1.0 1.4
userReference String Eingegebene Transaktions-Referenz
2.1 1.7
identifier String Die Transaktions-Referenz aus dem Terminal 
1.0 1.4
cardType String Die Eingabe-Methode der Karte.

Mögliche Werte:
01: Manuelle Eingabe
02: Magnetstreifen
05: Chipkarte
07: Kontaktlos

1.0 1.4


06: Timeout durch fehlende Signatur x 2.0 1.6

 

Stornieren einer Zahlung

Bitte beachten: Eine Transaktion kann nur bis zum nächsten Kassenschnitt storniert werden. Daher werden beim Kassenschnitt die identifier der übertragenen Zahlungen mit zurückgegeben.

Anfrage

Innerhalb der App kann mit folgendem Quellcode die Zahlung storniert werden:

let cancellation = RequestBuilder.cancellation(authKey: API_KEY, callbackScheme: URL-SCHEMA)
    .amount(amount)
    .identifier(identifier)
 
try cancellation.start()
Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
amount Integer Betrag in Cent x 1.0 1.4
identifier String Die Referenz der zu stornierenden Transaktion aus dem Terminal x 1.0 1.4


Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Zahlung automatisch storniert. Sollte die App nicht installiert sein, wird der Fehler RequestBuilderError.missingVRPaymeApp geworfen.

Antwort

Sobald die Zahlung storniert wurde, wird die VR-pay:Me App geschlossen. Die aufrufende App wird über das oben angegebene Callback-Scheme aufgerufen.

Im AppDelegate wird daraufhin vom System die Methode

func application(_ app:
    UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey :
    Any] = [:])

aufgerufen. Darin kann mit folgendem Code die Antwort ausgewertet werden:

guard let payment = try? ResponseHandler.parseCancellationResult(url: url) else {
    // Das Objekt enthält keine Antwort des VRPayment Frameworks
    ...
}
 
switch cancellation.status {
    case .SUCCESS:
        // "Storno wurde erfolgreich durchgeführt"
        ...
    case .FAILURE:
        // "Storno fehlgeschlagen"
        ...
    default:
        // Der Storno wurde nicht durchgeführt
        ...
        break
}

Folgende Werte kann der ResultStatus annehmen:

SUCCESS, // Vorgang erfolgreich
FAILURE, // Vorgang nicht erfolgreich
INVALID_INPUT, // Framework nicht korrekt aufgerufen (Kein Betrag übergeben)
NOT_READY, // Die VR-Pay:me App ist nicht vollständig eingerichtet
NO_CONNECTION // Es ist aktuell kein Terminal verbunden
APP_VERSION_TOO_LOW // Ab Lib Version 2.1
LIB_VERSION_TOO_LOW // Ab Lib Version 2.1

 

Kassenschnitt durchführen

Der Kassenschnitt muss durchgeführt werden damit die Zahlungen dem Konto gutgeschrieben werden.

Anfrage

Innerhalb der App kann mit folgendem Quellcode der Kassenschnitt durchgeführt werden:

let dataClearing = RequestBuilder
    .dataClearing(authKey: API_KEY, callbackScheme: URL-SCHEMA)
 
try dataClearing.start() 

Zum Starten des Kassenschnitts werden keine weiteren Daten benötigt.

Ist die VR-pay:Me App installiert, wird sie aufgerufen und der Kassenschnitt gestartet. Sollte die App nicht installiert sein, wird der Fehler RequestBuilderError.missingVRPaymeApp geworfen.

Antwort

Sobald die Zahlung durchgeführt wurde, wird die VR-pay:Me App geschlossen. Die aufrufende App wird über das oben angegebene Callback-Scheme aufgerufen.

Im AppDelegate wird daraufhin vom System die Methode

func application(_ app:
    UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey :Any] = [:])

aufgerufen. Darin kann mit folgendem Code die Antwort ausgewertet werden:

guard let dataClearing = try? ResponseHandler.parseDataClearingResult(url: url) else {
    // Das Objekt enthält keine Antwort des VRPayment Frameworks
    ...
}
 
switch dataClearing.status {
    case .SUCCESS:
        // Kassenschnitt wurde erfolgreich durchgeführt.
        ...
    case .FAILURE:
        // Kassenschnitt fehlgeschlagen.
        ...
    default:
        // Der Kassenschnitt wurde nicht durchgeführt
        ...
}

Folgende Felder sind im Objekt DataClearingResult vorhanden:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
status DataClearingResultStatus Statuscode der Anfrage x 1.0 1.4
receipt String Händlerbeleg für den Kassenschnitt
1.0 1.4
clearedIdentifier String-Array Identifier der Transkationen, die freigegeben wurden
1.0 1.4

 

Transaktion synchronisieren

Sollte der Status einer Transaktion nicht korrekt übertragen worden sein, kann mit der Funktion beginSync der Status der letzten Transkation abgerufen werden.

Anfrage

Innerhalb der App kann mit folgendem Quellcode die Synchronisation durchgeführt werden:

let sync = RequestBuilder
    .sync(authKey: API_KEY, callbackScheme: URL-SCHEMA)
 
try sync.start()

Zum Starten der Synchronisierung werden keine weiteren Daten benötigt.

Ist die VR-pay:Me App installiert, wird sie aufgerufen und die Synchronisierung gestartet. Sollte die App nicht installiert sein, wird der Fehler RequestBuilderError.missingVRPaymeApp geworfen.

Antwort

Sobald die Synchronisierung durchgeführt wurde, wird die VR-pay:Me App geschlossen und das Gerät springt in die aufrufende App zurück.

Im AppDelegate wird daraufhin vom System die Methode

func application(_ app:
    UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey :
    Any] = [:])

aufgerufen. Darin kann mit folgendem Code die Antwort ausgewertet werden:

guard let sync = try? ResponseHandler.parseSyncResult(url: url) else {
    // Das Objekt enthält keine Antwort des VRPayment Frameworks
    ...
}
 
switch sync.status {
    case .SYNC_OPERATION_SUCCEEDED:
        // Synchronisierung wurde erfolgreich durchgeführt.
        // Die Details zur letzten Aktion können dem entsprechenden Attribut entnommen werden.
        ...
    case .SYNC_OPERATION_FAILED:
        // Synchronisierung fehlgeschlagen.
        ...
    default:
        // Die Synchronisierung wurde nicht durchgeführt.
        ...
}

Da die Pending Transaction sowohl eine Zahlung, eine Stornierung oder ein Kassenschnitt sein kann, enthält das Objekt PendingTransaction alle Felder aus den drei Antworten:

Name Typ Beschreibung Erfor­derlich ab Lib Version ab App Version
status SyncResultStatus Folgende Werte kann der Status annehmen:

NOT_READY, // Die VR-Pay:me App ist nicht vollständig eingerichtet
NO_CONNECTION, // Es ist aktuell kein Terminal verbunden
SYNC_OPERATION_FAILED // Vorgang nicht erfolgreich
SYNC_OPERATION_SUCCEEDED // Vorgang erfolgreich
APP_VERSION_TOO_LOW // Ab Lib Version 2.1
LIB_VERSION_TOO_LOW // Ab Lib Version 2.1
x 1.0 1.4
amount Integer tatsächlicher Zahlbetrag in Cent x 1.0 1.4
identifier String Die Transaktions-Referenz aus dem Terminal 
1.0 1.4
maskedPan String Maskierte PAN
1.0 1.4
cardType String Die Eingabe-Methode der Karte.

Mögliche Werte:
01: Manuelle Eingabe
02: Magnetstreifen
05: Chipkarte
07: Kontaktlos

1.0 1.4
cardBrand String Kartengesellschaft. Wird aus der IIN der Transaktion ermittelt.
1.0 1.4
tax double Gewählter Mehrwertsteuersatz
1.0 1.4
customerReceipt String Kundenbeleg aus dem Terminal
1.0 1.4
date Date Datum der Transaktion
1.0 1.4
clearedIdentifier String-Array Identifier der Transkationen, die freigegeben wurden
1.0 1.4
Impressum | Datenschutz & Haftung