Das Pay:Me App-to-App SDK

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

 

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

Android

 

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

Zuerst legen Sie in der App ein neues Modul an.

Als Typ wählen Sie "AAR Package".

Im nächsten Schritt wählen Sie die "vr-payme-android-sdk-2.1.0-prodRelease.aar"-Datei, die Sie in dem ZIP File "vr-payme-android-sdk-2.1.0-prodRelease.aar.zip" finden. Anschließend vergeben Sie einen Namen für das Modul.

Sobald Sie das Library-Modul angelegt haben, können Sie es im gradle-Script des App-Moduls als Abhängigkeit referenzieren:

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?), die 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
        ...
    }
}

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:

 

Stornieren einer Zahlung

Bitte beachten Sie: 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
        ...
    }
}

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 ist Voraussetzung für die Gutschrift der Zahlungen auf dem Empfänger-Konto.

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:

 

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:

iOS

 

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

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

Haken Sie im Dialog Scheme "VRPaymeTestApp" an, damit es das Framework verfügbar ist.

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

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.

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()

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:

 

Stornieren einer Zahlung

Bitte beachten Sie: 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()

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 ist Voraussetzung für die Gutschrift der Zahlungen auf dem Empfänger-Konto.

Anfrage

Innerhalb der App können Sie mit folgendem Quellcode den Kassenschnitt durchführen:

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 ausgeworfen.

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:

 

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: