Bezahlmethode

Struktur

Eigene Zahlungsmethoden werden im Ordner Payments des übergeordneten Ordners Components eines Moduls angelegt. Alle Dateien, die für die Funktionsfähigkeit der Zahlungsmethode zwingend erforderlich sind, sind unten-stehend rot hervorgehoben.

  • Components
    • Payment
      • methoden_name
        • Gateway.php
        • logo.png

Parameter definieren

Parameter sind Werte, die benötigt werden, um das Gateway zu authentifizieren. Dies könnte beispielsweise ein API Schlüssel sein. Parameter werden in der Methode parameters(): array als Array definiert und automatisch mit der Registrierung der neuen Zahlungsmethode im System hinterlegt. Die Daten können im Anschluss bei den Einstellungen der etwaigen Zahlungsmethode definiert werden. Die Werte des Arrays werden wie im Folgenden gezeigt aufgabaut.

"technical_name" => "Human-readable name",

Zahlung initialisieren

Die Methode initializePayment(string $type, object $method, object $client, string $description, double $payment, object $invoice, string $returnCheckUrl, string $returnSuccessUrl, string $returnFailedUrl, string $returnNeutral, string $pingbackUrl) initialisiert eine neue Zahlung. Die Parameter der Methode sind beistehend beschrieben.

string $type Enthält die Art der Zahlung ("invoice" oder "prepaid").
object $method Enthält die Zugangsdaten der Zahlungsmethode, die in den Einstellungen hinterlegt wurden.
object $client Enthält die Daten des Kunden, dem der Zahlungsvorgang zuzuordnen ist.
string $description Enthält die Beschreibung des Zahlungsvorgangs. Es wird eine Idenfikationsnummer für die Zahlung selbst oder Rechnungsnummer übergeben.
double $payment Enthält den Wert der Zahlung inkl. MwSt.
object $invoice Enthält die Daten der Rechnung, die bezahlt wird, wenn $type den Wert invoice enthält.
string $returnCheckUrl Enthält die URL auf die der Nutzer weitergeleitet werden kann, wenn sofort nach dem Zahlungsvorgang eine Überprüfung der Zahlung vorgenommen werden soll. Der Aufruf dieser URL führt die Methode return(string $type, object $method, object $client): array der Zahlungsmethode aus.
string $returnSuccessUrl Enthält die URL auf die der Nutzer weitergeleitet werden kann, wenn die Zahlung erfolgreich abgeschlossen wurde. Dem Nutzer wird eine entsprechende Nachricht im Kundenbereich angezeigt.
string $returnFailedUrl Enthält die URL auf die der Nutzer weitergeleitet werden kann, wenn die Zahlung nicht erfolgreich abgeschlossen wurde. Dem Nutzer wird eine entsprechende Nachricht im Kundenbereich angezeigt.
string $returnNeutralUrl Enthält die URL auf die der Nutzer weitergeleitet werden kann, wenn der Status der Zahlung noch unbekannt ist. Dem Nutzer wird eine entsprechende Nachricht im Kundenbereich angezeigt.
string $pingbackUrl Enthält die URL, die vom Zahlungsanbieter als Pingback URL benutzt werden kann. Der Aufruf dieser URL führt die Methode pingback(string $type, object $method, object $client): array der Zahlungsmethode aus.

Rückkehr des Benutzers verarbeiten

Die Methode return(string $type, object $method, object $client) wird in der Regel direkt nach der Rückkehr des Benutzers zur Applikation verwendet. Sie kann direkt nach dem Zahlungvorgang den Status der Zahlung identifizieren und alle Belege im System entsprechend verarbeiten. Die Parameter der Methode sind beistehend beschrieben.

string $type Enthält die Art der Zahlung ("invoice" oder "prepaid").
object $method Enthält die Zugangsdaten der Zahlungsmethode, die in den Einstellungen hinterlegt wurden.
object $client Enthält die Daten des Kunden, dem der Zahlungsvorgang zuzuordnen ist.

Pingback verarbeiten

Die Methode pingback(string $type, object $method, object $client) verarbeitet anfragen des Payment Service Providers, die einen neuen Status einer Zahlung mitteilen. Die Funktionsweise der Methode ist vergleichbar mit der return Methode. Hier agiert jedoch kein Benutzer, sonder der Server des PSPs. Die Parameter der Methode sind beistehend beschrieben.

string $type Enthält die Art der Zahlung ("invoice" oder "prepaid").
object $method Enthält die Zugangsdaten der Zahlungsmethode, die in den Einstellungen hinterlegt wurden.
object $client Enthält die Daten des Kunden, dem der Zahlungsvorgang zuzuordnen ist.

Rückgaben

Rückgaben definieren den Status des etwaigen Zahlungsvorgangs. Die unten stehenden Stati sind derzeit vom Payment Method Framework interpretierbar.

Erfolgreicher Vorgang

Zahlung abgeschlossen

Die Zahlung wurde erfolgreich abgeschlossen. Die betroffenen Belege werden durch das Payment Method Framework als Payed markiert und Guthabenaufladungen werden verbucht.

return [
    "status" => "success",
    "payment_id" => $payment->metadata->mtid,
    "payment_status" => "success",
];

Zahlung fehlgeschlagen

Die Zahlung wurde abgebrochen. Es erfolgt keine Buchung durch das Payment Method Framework. Die Zahlung wird als Failed markiert.

return [
    "status" => "success",
    "redirect" => $returnFailedUrl,
    "payment_id" => $mtid,
    "payment_status" => "failed",
];

Zahlung zurückgebucht

Die Zahlung wurde vom Zahlungsanbieter zurückgebucht. Das Payment Method Framework markiert alle betroffenen Rechnungen erneut als Unpaid und bucht alle erfolgreichen Guthaben-Aufladungen zurück. In der Regel wird dieser Status durch den Payment Service Provider als Pingback mitgeteilt.

return [
    "status" => "success",
    "payment_id" => $payment->metadata->mtid,
    "payment_status" => "revoked",
];

Pingback ausstehend

Die Zahlung wurde erfolgreich initialisiert, der Status konnte jedoch nicht sofort identifiziert werden. Die Identifizierung erfolgt über ein Pingback. Dem Nutzer wird bei dieser Rückgabe eine entsprechende Nachricht im Kundenbereich angezeigt, dass seine Zahlung derzeit noch verarbeitet wird. Wird der Key redirect gesetzt, so wird der Nutzer an die definierte URL statt die Zahlungsmaske weitergeleitet. Die Zahlung wird als Waiting markiert.

return [
    "status" => "success",
    "redirect" => $payment->getCheckoutUrl(),
    "payment_id" => $mtid,
    "payment_status" => "waiting",
];

Technischer Fehler

Es ist ein technischer Fehler bei der Initialisierung der Zahlung aufgetreten. Erhält das Payment Method Framework diesen Status, werden jegliche weiterführende Verarbeitungs-Logiken abgebrochen. Die Zahlung wird nicht weiter verarbeitet.

return [
    "status" => "false",
    "redirect" => null,
    "payment_id" => null,
    "payment_status" => "",
];

Gateway.php

Herunterladen: Gateway.php

<?php

namespace Modules\Sample\Components\Payment\Sample;

class Gateway
{
    /**
     * Register the parameters which are being used by the payment method
     * (e.g. to authenticate against the API).
     * 
     * @return string[]
     */
    public function parameters()
    {
        return [
            "apikey" => "API Key",
            "apisecret" => "API Secret"
        ];
    }

    /**
     * Get the real name for the payment method. This may contain formatted,
     * human readable text.
     * 
     * @return string
     */
    public function getName()
    {
        return "Sample";
    }

    /**
     * Technical name for the payment method. This may only contain lower-case 
     * letters, dashes, underscores and numbers to ensure that the string is 
     * fully readable by PHP.
     * 
     * @return string
     */
    public function getTechnicalName()
    {
        return "sample";
    }

    /**
     * Initialize a new payment. This should either return a result array or
     * redirect the user directly.
     *
     * @param $type
     * @param $method
     * @param $client
     * @param $description
     * @param mixed $payment Either an invoice object or the amount which the user has to pay
     * @param $returnCheckUrl
     * @param $returnSuccessUrl
     * @param $returnFailedUrl
     * @param $returnNeutral
     * @param string $pingbackUrl
     *
     * @return array|false
     */
    public function initializePayment($type, $method, $client, $description, $payment, $invoice, $returnCheckUrl, $returnSuccessUrl, $returnFailedUrl, $returnNeutralUrl, $pingbackUrl) 
    {
        if ($type == "invoice") {
            return [
                "status" => "success",
                "redirect" => "url",
                "payment_id" => "payment_id",
                "payment_status" => "",
            ];
        } elseif ($type == "prepaid") {
            return [
                "status" => "false",
                "redirect" => null,
                "payment_id" => null,
                "payment_status" => "",
            ];
        }
    }

    /**
     * This function is called when the user returns to the page. It may already
     * check for the current payment status.
     * 
     * @return array|false
     */
    public function return($type, $method, $client) 
    {
        if ($type == "invoice") {
            return [
                "status" => "success",
                "payment_id" => "payment_id",
                "payment_status" => "",
            ];
        } elseif($type == "prepaid") {
            return [
                "status" => "false",
                "redirect" => "https://somepage.de",
                "payment_id" => null,
                "payment_status" => "",
            ];
        }
    }

    /**
     * This function is called when a pingback is received by the payment service provider.
     * It may already check for the current payment status.
     *
     * @param $type
     * @param $method
     * @param $client
     * 
     * @return array|false
     */
    public function pingback($type, $method, $client)
    {
        if ($type == "invoice") {
            return [
                "status" => "success",
                "payment_id" => "payment_id",
                "payment_status" => "",
            ];
        } elseif($type == "prepaid") {
            return [
                "status" => "false",
                "payment_id" => null,
                "payment_status" => "",
            ];
        }
    }
}