worldline Direct
Sign up

Aktuellste API Basis-URL nutzen

Wir raten Ihnen, immer die aktuellste API Basis-URL zu nutzen, wenn Sie Anfragen an unsere Plattform senden. In unseren ausführlichen Anleitungen finden Sie eine komplette Übersicht:

Für einen reibungslosen Übergang bleiben vorherige API Basis-URLs bis auf weiteres verfügbar.

Zum Erstellen von Zahlungen müssen Sie Ihren Server über einen unserer Integrationsmodi mit unserer Plattform verbinden.
Unsere PHP SDK-Bibliothek ist die ideale Lösung zur Verbindung mit unserer Plattform, wenn Sie es vorzugsweise mit Ihrem eigenständigen System in der Sprache PHP tun möchten.

Durch Auswahl des PHP SDK können Sie:

Damit Sie die Möglichkeiten dieses SDK voll ausschöpfen können, müssen Sie diese Anforderungen erfüllen:

  • PHP 5.4 oder höher
  • Ausdrücklich empfohlen: Installation des Tools Composer

Die neueste Version des PHP SDK können Sie herunterladen und installieren:

  • mit dem Git-Systems auf GitHub
  • mit dem von Composer bereitgestellten Code
  • durch manuelle Installation unserer Bibliothek auf Ihrem System

Nähere Einzelheiten erfahren Sie auf GitHub. Sehen Sie sich auch alle verfügbaren SDK-Objekte und -Eigenschaften in unserer vollständigen API-Referenz an. Wenn alles bereit ist, lesen Sie bitte die nächsten Kapitel über die Vorbereitung und Verwendung des SDK.

Diese Anleitung gibt einen allgemeinen Überblick über die Funktionen des SDK. Wie sie für die verschiedenen Integrationsmodi genau funktionieren, erfahren Sie in den speziellen Anleitungen, die jeden Schritt mit vollständigen Code-Beispielen erklären:

Damit Sie das SDK zur Verbindung Ihres Systems mit unserer Plattform nutzen können, müssen Sie es zunächst initialisieren.

Zum Initialisieren müssen Sie:

  • Ein Test- und Live-Konto einrichten
  • Einen API-Schlüssel und ein API-Geheimnis für die PSPID erzeugen, die Sie für die Transaktionsverarbeitung verwenden möchten
  • Eine Instanz von Client unter Verwendung des API-Schlüssels/API-Geheimnisses initialisieren, um die Verbindung zu unserer Test-/Live-Plattform herzustellen

Nach der Initialisierung können Sie mit der Verarbeitung von Transaktionen über Ihre PSPID beginnen. Wie das funktioniert, erfahren Sie in dem entsprechenden Kapitel.

Sehen Sie sich das Code-Beispiel an, das die oben genannten Schritte abdeckt:

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • DefaultConnection
  • CommunicatorConfiguration
  • Communicator
  • Client
  • ProxyConfiguration

$connection = new DefaultConnection();

// Ihre PSPID in unserer Test- oder Live-Umgebung
$merchantId = "PSPID";

// Geben Sie den Wert des API-Schlüssels an, den Sie im Merchant Portal finden
$apiKey = 'API KEY'; 

// Geben Sie den Wert des API-Geheimnisses an, den Sie im Merchant Portal finden
$apiSecret = 'API Secret';   
 
// Dieser Endpunkt verweist auf den TEST-Server 
// Hinweis: Verwenden Sie hier den Endpunkt ohne den Teil /v2/
$apiEndpoint = 'https://payment.preprod.direct.worldline-solutions.com/';

// Weitere Einstellungen zur einfachen Identifizierung Ihres Unternehmens in unseren Protokollen.
$integrator = 'IHR FIRMENNAME';
 
$proxyConfiguration = null;
/* 
* Zum Verwenden des Proxy müssen Sie den Abschnitt unten auskommentieren
* und die entsprechenden Einstellungen durch Ihre Proxy-Einstellungen ersetzen.
* (außerdem können Sie die vorherige Einstellung kommentieren).
*/
/* 
$proxyConfiguration = new ProxyConfiguration(
    'proxyHost', 
    'proxyPort', 
    'proxyUserName', 
    'proxyPassword'
);
*/
$communicatorConfiguration = new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);
 
$communicator = new Communicator($connection, $communicatorConfiguration);

$client = new Client($communicator);

$merchantClient = $client->merchant($merchantId);


Die folgende Tabelle gibt einen Überblick über die Argumente, die von den einzelnen Instanzen akzeptiert werden:

Eigenschaften
  • string $merchantId: Ihre PSPID in unserer Test-Umgebung oder Live-Umgebung. Achten Sie darauf, dass Sie den korrekten apiKey / das korrekte apiSecret zusammen mit der dazugehörigen PSPID für Ihre Transaktionsanfrage verwenden
  • string $apiKey: Der API-Schlüssel, den Sie in Ihrer PSPID definiert haben und an den Sie die Transaktionen senden
  • string $apiSecret: Das API-Geheimnis, das Sie in Ihrer PSPID definiert haben und an das Sie die Transaktionen senden
    In unserer speziellen Anleitung erfahren Sie alles zum Thema $apiKey / $apiSecret
  • string $apiEndpoint: Enthält einen Link zu unserer Test- oder Live-Umgebung, an die Ihre Transaktionsanfragen gesendet werden
  • string $integrator: Ihr (Firmen-)Name oder eine andere eindeutige Kennung. Wir können den Wert zur Fehlersuche und Nachverfolgung von Anfragen, die Sie an unsere Plattform gesendet haben, verwenden. Darum empfehlen wir dringend, einen Wert zu senden, mit dem wir Ihre Anfragen in unseren Protokollen einfach identifizieren können
Eine Client-Instanz können Sie für verschiedene Aufrufe wiederverwenden. Sie können verwenden:

  • Das Objekt der Klasse MerchantClient, das im Beispiel für alle Aufrufe für diese PSPID initialisiert wurde 
    Durch Aufruf dieser Code-Zeile erhalten Sie das MerchantClient-Objekt:
    $client->merchant($merchantId)
    
  • Die Client-Instanz zum Erzeugen von MerchantClients für verschiedene (oder dieselben) PSPIDs


Nachdem Sie das SDK initialisiert haben, können Sie über Ihre PSPID Anfragen an unsere Plattform senden. Wie Sie das tun, erfahren Sie Im nächsten Kapitel.

As our SDKs always implement the latest version of our API, you can leave out "v2" in your code as shown in the example above.

Remember to pay attention to the environment you get the key set from. API Key and API Secret are different for test and live environments.

The full path of the of API endpoint for test/live environment is

  • https://payment.preprod.direct.worldline-solutions.com/v2/
  • https://payment.direct.worldline-solutions.com/v2/

respectively. If you are ready to switch to the live environment, substitute the endpoint link apiEndpoint = 'https://payment.preprod.direct.worldline-solutions.com/' for the live environment apiEndpoint = 'https://payment.direct.worldline-solutions.com/'

For transactions with no financial impact, use TEST-URL. The transactions will be sent to our test environment, thereby to your test account.

For transactions with a financial impact, use the LIVE-URL. The transactions will be sent to our live environment, thereby to your live account.

Nach der erfolgreichen Initialisierung der Client-Instanz haben Sie vollen Zugang zu unserer RESTful API. Damit können Sie:

  • Anfragen für neue Transaktionen für jeden unserer Server-Integrationsmodi senden
  • den aktuellen Status Ihrer Transaktionen abfragen
  • Wartungsanfragen (z. B. Erfassungen, Gutschriften) für bestehende Transaktionen durchführen

Stellen Sie Sicher, dass die Bezahlmethode, die Sie benutzen wollen, in Ihrem Test-/Livekonto aktiv ist. Überprüfen Sie dies im Back Office via Configuration > Payment methods

Sehen Sie sich unsere Testfälle auf GitHub mit vollständigen Codebeispielen an. In unserer vollständigen API-Referenz erfahren Sie, was alles möglich ist.

Nachstehend finden Sie einige der häufigsten Aktionen, die Sie durchführen können:

Neue Transaktionen erstellen

Zum Erstellen einer neuen Transaktion können Sie eine Client-oder MerchantClient-Instanz für einen unserer Integrationsmodi verwenden. Dazu können Sie:

  • die Anfrage an Ihre PSPID auf unserer Plattform (für Client) leiten
  • eine Anfrage für den betreffenden Integrationsmodus erstellen

Die SDK-Instanz speichert nur die Daten, die zu ihrer Initialisierung verwendet wurden. Sie speichert weder aktive Sessions noch frühere Anfragen. Ihr System ist für die Verwaltung von Direct-Sessions und -Zahlungen verantwortlich

Sessions und Zahlungen haben keine Auswirkungen auf andere Sessions und Zahlungen

Nachfolgend finden Sie Codebeispiele für bestimmte Integrationsmodi:

Hosted Checkout Page

Zum Nutzen dieses Integrationsmodus müssen Sie einen CreateHostedCheckoutRequest-Aufruf erstellen. Er muss mindestens ein Order-Objekt enthalten.

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • CreateHostedCheckoutRequests
  • Order
  • AmountOfMoney


/* *…. Initialisierung.... */ $merchantClient = $client->merchant($merchantId); /* */ $hostedCheckoutClient = $merchantClient->hostedCheckout(); $createHostedCheckoutRequest = new CreateHostedCheckoutRequest(); $order = new Order(); // Das Beispielobjekt AmountOfMoney $amountOfMoney = new AmountOfMoney(); $amountOfMoney->setCurrencyCode("EUR"); $amountOfMoney->setAmount(100); $order->setAmountOfMoney($amountOfMoney); $createHostedCheckoutRequest->setOrder($order); // Antwort für HostedCheckoutClient abrufen $createHostedCheckoutResponse = $hostedCheckoutClient->createHostedCheckout( $createHostedCheckoutRequest );
Auf Wunsch können Sie eine returnUrl angeben, die dafür verwendet wird, Ihren Kunden wieder zu Ihrer Website weiterzuleiten

Bei diesem Aufruf wird eine CreateHostedCheckoutResponse-Antwort zurückgegeben. Speichern Sie die darin enthaltenen Werte hostedCheckoutId und RETURNMAC sowie alle anderen für Sie relevanten Informationen. Diese Daten brauchen Sie für die in den folgenden Kapiteln beschriebenen Schritte.

Diese Antwort enthält auch eine partialRedirectURL.

Sie müssen die Basis-URL „https://payment.“ mit partialRedirectURL nach folgender Formel verketten:

https://payment. + partialRedirectURL

und Ihren Kunden zu dieser URL weiterleiten. Sobald der Kunde die Seite Hosted Checkout Page besucht, wird der Zahlungsvorgang dort fortgesetzt.

Die neueste Version unseres SDKs gibt in redirectURL auch den vollständigen Pfad zurück, daher können Sie die Verkettung der Basis-URL „https://payment.“ mit partialRedirectURL überspringen. Weitere Einzelheiten erfahren Sie in unserer Anleitung zu Hosted Checkout Page

Hosted Tokenization Page

Um diese Integrationsmethode zu verwenden, müssen Sie:

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • CreateHostedTokenizationRequest

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

/*
    
  
 */
$hostedTokenizationClient = 
$merchantClient->hostedTokenization();

$createHostedTokenizationRequest = 
new CreateHostedTokenizationRequest();

// Ihre Vorlage festlegen
$createHostedTokenizationRequest->setVariant(
"my-custom-template.html"
);

// Antwort für HostedTokenizationClient abrufen
$createHostedTokenizationResponse = $hostedTokenizationClient
->createHostedTokenization(
$createHostedTokenizationRequest
);

Rufen Sie aus CreateHostedTokenizationResponse hostedTokenizationId als $hostedTokenizationId und partialRedirectUrl als $partialRedirectUrl ab. Verwenden Sie die partialRedirectUrl für den iframe und $hostedTokenizationId oder $tokenId (siehe Infobox) zum Erstellen der eigentlichen Zahlung über den Integrationsmodus Server-to-server.

In Ihrer CreatePayment-Anfrage können Sie entweder die tokenID oder die hostedTokenizationId senden. Mehr über die Verwendung beider Optionen erfahren Sie in den entsprechenden Kapiteln unserer Anleitung zu Hosted Tokenization Page:

$hostedTokenizationId = $createHostedCheckoutResponse->getHostedTokenizationId(); 
$partialRedirectUrl = $createHostedCheckoutResponse->getPartialRedirectUrl(); 
$createPaymentRequest = new CreatePaymentRequest(); 
 
$order = new Order(); 
 
$amountOfMoney = new AmountOfMoney(); 
$amountOfMoney->setCurrencyCode("EUR"); 
$amountOfMoney->setAmount(100); 
$order->setAmountOfMoney($amountOfMoney); 
 
$createPaymentRequest->setOrder($order);
$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput(); $cardPaymentMethodSpecificInput->setTokenize(true); $cardPaymentMethodSpecificInput->setToken($hostedTokenizationId); $createPaymentRequest->setCardPaymentMethodSpecificInput( $cardPaymentMethodSpecificInput ); // Antwort für PaymentsClient abrufen $createPaymentResponse = $paymentsClient->createPayment($createPaymentRequest);

Server-to-server

Für eine minimale paymentResponse müssen Sie mindestens ein Order-Objekt und eine Zahlungsmethode festlegen:

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • CreatePaymentRequest
  • AmountOfMoney
  • Card
  • CardPaymentMethodSpecificInput
  • Order

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

/*
   
  
 */
$paymentsClient = $merchantClient->payments();

$createPaymentRequest = new CreatePaymentRequest(); 

$order = new Order();

// Das Beispielobjekt AmountOfMoney 
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);

$createPaymentRequest->setOrder($order);
$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput(); // Das Beispielobjekt der Karte $card = new Card(); $card->setCvv("123"); $card->setCardNumber("4111111111111111"); // // Mehr Testdaten finden Sie here $card->setExpiryDate("1236"); $card->setCardholderName("Wile E. Coyote"); $cardPaymentMethodSpecificInput->setCard($card); $createPaymentRequest->setCardPaymentMethodSpecificInput( $cardPaymentMethodSpecificInput ); // Antwort für PaymentsClient abrufen $createPaymentResponse = $paymentsClient->createPayment($createPaymentRequest);

Für jeden der oben genannten Integrationsmodi haben wir eine eigene Anleitung:

In den Dokumenten erfahren Sie alle wichtigen Einzelheiten, einschließlich vollständiger Transaktionsabläufe, Code-Beispiele und anderer nützlicher Funktionen, damit Sie das Potenzial der Integrationsmodi voll ausschöpfen können

Transaktionsstatus abrufen

Mit unserer RESTful API können Sie den Status einer Transaktion jederzeit mit einem unserer GET-Aufrufe abfragen:

Eine GetPayment-Anfrage sieht so aus:


$merchantClient = $client->merchant($merchantId);

// Antwort für PaymentsClient abrufen
$createPaymentResponse = 
$paymentsClient->createPayment($createPaymentRequest);

// Hier rufen Sie $paymentId zur Verwendung im weiteren Code ab
$paymentID = $createPaymentResponse->getPayment()->getId();

// Objekt PaymentResponse mit Statusinformationen
// zur Zahlung mit der betreffenden ID
$paymentResponse = $merchantClient
->payments()
->getPayment($paymentID);
Merkmale
string $paymentID: Die eindeutige Referenz Ihrer Transaktion auf unserer Plattform. Diese Referenz kann aus der im vorherigen Abschnitt erstellten CreatePaymentResponse oder createHostedCheckoutResponse abgerufen werden.

Weitere Informationen über Statuswerte finden Sie auf der Dokumentationsseite zu Statuswerten.

Wartungsmaßnahme durchführen

Zum Ausführen von Folgemaßnahmen für bestehende Transaktionen (d. h. Erfassungen oder Gutschriften) verwenden Sie unseren API-Aufruf CapturePayment bzw. RefundPayment:

CapturePayment

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • CapturePaymentRequest

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

/*
 * . ...
 */

// $paymentId zur Verwendung im weiteren Code abrufen
$paymentID = $createPaymentResponse->getPayment()->getId();

/*
 * . ...
 */

$capturePaymentRequest = new CapturePaymentRequest();
$capturePaymentRequest->setAmount(100);
$capturePaymentRequest->setIsFinal(true);

// Objekt CaptureResponse abrufen
$captureResponse = $merchantClient
->payments()
->capturePayment(
$paymentID, 
$capturePaymentRequest
);

RefundPayment

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • RefundRequest
  • AmountOfMoney
/*  
 *…. Initialisierung.... 
 */ 
 
$merchantClient = $client->merchant($merchantId); 

/* 
 * . ... 
 */ 

// $paymentId zur Verwendung im weiteren Code abrufen 
$paymentID = $createPaymentResponse->getPayment()->getId(); 

/* 
 * . ... 
 */ 

$refundRequest = new RefundRequest(); 

$amountOfMoney = new AmountOfMoney(); 
$amountOfMoney->setCurrencyCode("EUR"); 
$amountOfMoney->setAmount(100); 

$refundRequest->setAmountOfMoney($amountOfMoney); 


// Objekt RefundResponse abrufen 
$refundResponse = $merchantClient 

	->payments() 
	->refundPayment( 
		$paymentID,  
		$refundRequest 
	); 
Merkmale
string $paymentID: Die eindeutige Referenz Ihrer Transaktion auf unserer Plattform. Diese Referenz kann aus der im vorherigen Abschnitt erstellten CreatePaymentResponse oder createHostedCheckoutResponse abgerufen werden.

Wenn eine Transaktion abgelehnt wird, gibt unsere Plattform mit einer Exception-Instanz ausführliche Informationen. Auch der zugehörige HTTP-Status-Code hilft Ihnen bei der Fehlersuche.

Es können zwei Arten von Ausnahmen auftreten: Transaktionsausnahmen und HTTP-Ausnahmen.

Transaktionsausnahmen

Ausnahmen dieser Art beziehen sich auf Transaktionsanfragen, die technisch korrekt sind, aber vom Kreditkartenherausgeber Ihres Kunden oder Ihrem Acquirer abgelehnt wurden. Wenn die Transaktion in der Ausnahme zurückgegeben wird, dann wurde sie in unseren Systemen erstellt, aber nicht erfolgreich verarbeitet.

Die folgenden Code-Beispiele verwenden implizite Methoden, die als Beispiel dienen sollen. Von Ihnen wird erwartet, dass Sie diese selbst implementieren oder durch eine ähnliche Logik ersetzen
Ausnahmetyp /
HTTP-Statuscode
Code-Beispiel
Abgelehnte Transaktionen /
Verschiedenes (siehe Objekt PaymentResponse)

/*
 * Initialisierung....
 */
$paymentID = ""; $createPaymentRequest = new CreateRequest(); try {
$createPaymentResponse =
$paymentsClient->createPayment( $createPaymentRequest );
$paymentID = $createPaymentResponse ->getPayment()->getId();
}
catch (DeclinedPaymentException $e) {
$paymentResult = $e->getPaymentResult();
$payment = $paymentResult->getPayment();
handleError($payment);
return;
}
$paymentResponse = $merchantClient
->payments()->getPayment($paymentID); // Ihr Code zur Prüfung des Transaktionsstatus und // Fehlerbehandlung
if (isNotSuccessful($paymentResponse)) {
handleError($paymentResponse);
}
Abgelehnte Gutschrift /
Verschiedenes (siehe Objekt PaymentResponse)
/*
 * Initialisierung....
 */
$paymentID = $createPaymentResponse
->getPayment()->getId();
$refundID = "";
$refundRequest = new CreateRequest();
try {
// Objekt RefundResponse abrufen
$refundResponse = $merchantClient
->payments()
->refundPayment(
$paymentID,
$refundRequest
);

$refundID = $refundResponse->getId();
}
catch (DeclinedRefundException $e) {
$refundResult = $e->getRefundResult();
handleError($refundResult);
return;
}

$refundResponse = $merchantClient
->payments()
->refundPayment($paymentID, $refundRequest); // Ihr Code zur Prüfung des Transaktionsstatus und // Fehlerbehandlung
if (isNotSuccessful($refundResponse, $refundID)) {
handleError($refundResponse);
}

HTTP-Ausnahmen

Derartige Ausnahmen beziehen sich auf verschiedene Probleme, die auf technische Fehler beim API-Aufruf oder bei der Zahlungsanforderung zurückzuführen sind.

Sie können jeden der folgenden Code-Schnipsel mit dieser Standard-CreatePayment-Anfrage kombinieren:

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • ApiException

/* 
 *…. Initialisierung....
 */

$createPaymentRequest = new CreatePaymentRequest(); 

$order = new Order();

// Das Beispielobjekt AmountOfMoney 
$amountOfMoney = new AmountOfMoney();
$amountOfMoney->setCurrencyCode("EUR");
$amountOfMoney->setAmount(100);
$order->setAmountOfMoney($amountOfMoney);
 
$createPaymentRequest->setOrder($order);
$cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput(); // Das Beispielobjekt der Karte - Testkarten finden Sie auf // /documentation/test-cases/ $card = new Card(); $card->setCvv("123"); $card->setCardNumber("4111111111111111"); $card->setExpiryDate("1236"); $card->setCardholderName("Wile E. Coyote"); $cardPaymentMethodSpecificInput->setCard($card); $createPaymentRequest->setCardPaymentMethodSpecificInput( $cardPaymentMethodSpecificInput ); try { // Antwort für PaymentsClient abrufen $createPaymentResponse = $paymentsClient ->createPayment($createPaymentRequest); } catch (ApiException $e) { // Siehe Liste unten, wie spezifische // Implementierungen von ApiException behandelt werden können. }
Ausnahmetyp /
HTTP-Statuscode
Code-Beispiel
ValidationException /
400
catch (ValidationException $e) {
$message = 'Fehler bei Input-Validierung:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ';
if (!empty($error->getPropertyName())) {
$message .= $error->getPropertyName() . ': ';
}
$message .= $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen
}
AuthorizationException /
403

catch (AuthorizationException $e) {
$message = 'Autorisierungsfehler:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ' . $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen
}
IdempotenceException /
409

catch (IdempotenceException $exception) {
$message = 'Idempotenz-Fehler:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ' . $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen
}
ReferenceException /
404/409/410

catch (ReferenceException $e) {
$message = 'Falsche Objektreferenz:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ' . $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen }
DirectException /
500/502/503

catch (DirectException $e) {
$message = 'Fehler aufgetreten bei Direct oder';
$message .= 'einem nachgeordneten Partner/Acquirer:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ' . $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen
}
ApiException /
Sonstige Codes

catch (ApiException $e) {
$message = 'Unerwarteter Fehler:' . PHP_EOL;
foreach ($e->getErrors() as $error) {
$message .= '- ' . $error->getMessage();
$message .= '(' . $error->getCode() . ')' . PHP_EOL;
}
// Etwas mit $message machen
}

HTTP-Statuscodes

Alle unsere Ausnahmen sind mit einem oder mehreren HTTP-Statuscodes verbunden, die die Ursache für viele mögliche Fehler angeben.

Statuscode Beschreibung Ausnahmetyp
200

Successful
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet

-
201

Created
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet und eine neue Ressource erstellt. Den URI dieser Ressource geben wir im Header Location der Antwort zurück

-
204

No content
Unsere Plattform hat Ihre Anfrage korrekt bearbeitet

-
Verschiedenes
Schlüssel paymentResult ist in der Antwort

Payment Rejected
Unsere Plattform oder einer unserer nachgeordneten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedPaymentException
Verschiedenes
Schlüssel payoutResult ist in der Antwort

Payout Rejected
Unsere Plattform oder einer unserer nachgeordneten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedPayoutException

Verschiedenes
Schlüssel refundResult ist in der Antwort

Refund Rejected
Unsere Plattform oder einer unserer nachgeordneten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedRefundException
400

Bad Request
Ihre Anfrage enthält Fehler, deshalb kann unsere Plattform sie nicht verarbeiten

ValidationException
403

Not Authorised
Sie versuchen, etwas zu tun, das nicht erlaubt ist oder zu dem Sie nicht befugt sind

AuthorizationException
404

Not Found
Das Objekt, auf das Sie zugreifen wollten, konnte auf dem Server nicht gefunden werden.

ReferenceException
409

Conflict
Ihre idempotente Anfrage hat zu einem Konflikt geführt, weil sie entweder:

  • Die erste Anfrage noch nicht abgeschlossen ist oder
  • Ihre Anfrage zu einem Konflikt geführt hat. Entweder haben Sie eine doppelte Anfrage gestellt oder Sie versuchen, etwas mit einem doppelten Schlüssel zu erstellen
IdempotenceException
ReferenceException
410

Gone
Das Objekt, das Sie zu erreichen versuchen, wurde entfernt.

ReferenceException
500

Internal Server Error
Auf unserer Plattform ist ein Fehler aufgetreten

DirectException
502 Bad Gateway
Unsere Plattform konnte eine Nachricht von einem nachgeordneten Partner/Acquirer nicht verarbeiten
DirectException
503 Service Unavailable
Der Dienst, den Sie zu erreichen versuchen, ist vorübergehend nicht verfügbar. Bitte versuchen Sie es später noch einmal
DirectException
Sonstiges Unexpected error
Ein unerwarteter Fehler ist aufgetreten
ApiException

Das SDK hat noch viel mehr zu bieten. Sehen Sie sich die folgenden Möglichkeiten an, denn sie helfen Ihnen beim Entwickeln der perfekten Lösung.

Verfügbare Zahlungsarten abrufen

Bevor Sie den eigentlichen Zahlungsvorgang einleiten, sollten Sie eine GetPaymentProducts-Anfrage an unsere Plattform senden. Die Antwort enthält eine Liste der in Ihrer PSPID verfügbaren Zahlungsarten. Je nach den Vorlieben Ihrer Kunden können Sie eine Auswahl auf unserer Hosted Checkout Page oder in Ihrer eigenen Webshop-Umgebung mit nachfolgenden CreatePayment-Anfragen anbieten.

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • GetPaymentProductsParams

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

// Anfrage zum Abruf aller aktiven Zahlungsmethoden in Ihrer PSPID erstellen
$queryParams = new GetPaymentProductsParams();

// Beispiel-Parameter
$queryParams->setCountryCode("BE");
$queryParams->setCurrencyCode("EUR");

// Anfrage senden und Antwort abrufen
$paymentProductsResponse = $merchantClient
    ->products()
    ->getPaymentProducts($queryParams);

Idempotente Anfragen senden

Eines der wichtigsten Merkmale der REST-API ist ihre Fähigkeit, versehentlich doppelt gesendete Anfragen (z. B. Zahlungsanfragen) zu erkennen und zu verhindern. Mit dem SDK können Sie sehr einfach sicherstellen, dass Sie nur einmalige (idempotente) Anfragen an unsere Plattform senden.

Dazu verwenden Sie das zusätzliche Argument CallContext und setzen Sie seine Eigenschaft $idempotenceKey mit dem Aufruf von setIdempotenceKey() für das zuvor erstellte Objekt, und dann rufen Sie die API-Funktion CreatePayment auf. Das SDK sendet einen X-GCS-Idempotence-Key-Header mit dem idempotence-Schlüssel als Wert.

Wenn Sie auf diese Weise Anfragen an unsere Plattform senden, überprüfen wir Folgendes:

  • Wenn Sie eine weitere Anfrage mit demselben Idempotence-Schlüssel senden, enthält die Antwort einen X-GCS-Idempotence-Request-Timestamp-Header. Das SDK setzt die Eigenschaft $idempotenceRequestTimestamp des ArgumentsCallContext
  • Wenn die erste Anfrage noch nicht abgeschlossen ist, gibt die RESTful Server API einen Statuscode 409 zurück. Dann wirft das SDK eine IdempotenceException mit dem ursprünglichen Idempotenzschlüssel und dem Zeitstempel der idempotenten Anfrage
Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • CallContext
  • IdempotenceException

/* 
 *…. Initialisierung....
 */

$merchantClient = $client->merchant($merchantId);

$createPaymentRequest = new CreatePaymentRequest();

$idempotenceKey = "YourKeyForThePayment";
 
$callContext = new CallContext();
$callContext->setIdempotenceKey($idempotenceKey);

try {
    $createPaymentResponse = $merchantClient
        ->payments()
        ->createPayment(
            $createPaymentRequest, 
            $callContext
        );
} catch (IdempotenceException $e) {
    // Eine Anfrage mit demselben $idempotenceKey läuft noch, nach einer kurzen Pause noch einmal versuchen
    // $e->getIdempotenceRequestTimestamp() enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
} finally {
    $idempotenceRequestTimestamp = 
        $callContext->getIdempotenceRequestTimestamp();
    // $idempotenceRequestTimestamp enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
    // wenn $idempotenceRequestTimestamp nicht leer ist, war dies nicht die erste Anfrage
}

Wenn ein Idempotenz-Schlüssel für einen Aufruf gesendet wird, der Idempotenz nicht unterstützt, ignoriert die RESTful Server API den Schlüssel und behandelt die Anfrage als erste Anfrage.


Protokollierung verwenden

Das SDK unterstützt die Protokollierung von Anfragen, Antworten und Exceptions. Diese Protokolle können hilfreich bei der Fehlersuche oder der Nachverfolgung einzelner Schritte im Zahlungsablauf sein.
Das SDK bietet zwei Implementierungen der Protokollierungsfunktion:

  • SplFileObjectLogger (durch Verwendung von SplFileObject)
  • ResourceLogger
Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • ResourceLogger

Die Protokollierung können Sie aktivieren/deaktivieren durch Aufruf von:


/* 
 *…. Initialisierung....
 */

$client = new Client($communicator);

// Sie können einen Pointer zu der Datei eingeben, in der Sie 
// Daten anstelle von STDOUT speichern möchten
$logger = new ResourceLogger(STDOUT); 
$client->enableLogging($logger); 
//... Aufrufe ausführen 
$client->disableLogging();
Sensible Daten verschleiert das SDK im Logger

Verbindungs-Pooling

Ihre Netzwerkressourcen können Sie verwalten, indem Sie die Zahl der möglichen Verbindungen begrenzen, die das SDK aufbaut und aufrechterhält. Client-Instanzen, die wie im Kapitel SDK initialisieren beschrieben erzeugt wurden, haben ihren eigenen Verbindungspool. Mit demselben Communicator-Objekt erzeugte Client-Instanzen teilen sich einen Verbindungspool.

Wenn Sie mehrere Client-Instanzen verwenden, die sich einen einzigen Verbindungspool teilen, müssen Sie die folgenden Schritte ausführen:

  1. Einen gemeinsamen Communicator erzeugen
  2. Client-Instanzen mit diesem Communicator erzeugen

/* 
 *…. Initialisierung....
 */

// CommunicatorConfiguration-Instanz 
// mit richtigen Einstellungen erzeugen
$sharedCommunicatorConfiguration = 
new CommunicatorConfiguration(
    $apiKey,
    $apiSecret,
    $apiEndpoint,
    $integrator,
    $proxyConfiguration
);
 
$connection = new DefaultConnection();

// Communicator-Instanz
$communicator = new Communicator(
$connection, 
$sharedCommunicatorConfiguration
);
 
$client1 = new Client($communicator);
$client2 = new Client($communicator);

Kommunikation anpassen

Die Client-Instanzen kommunizieren über eine Communicator-Instanz mit unserer Plattform. Der Communicator hingegen verwendet Connection für die eigentlichen HTTP-Anfragen, und ConnectionResponse zum Speichern der HTTP-Antwort.

Connection und ConnectionResponse sind Schnittstellen. Das SDK bietet eine Standardimplementierung dieser Schnittstellen mit den Klassen DefaultConnection und DefaultConnectionResponse.

  • Die Klasse DefaultConnection verwendet cURL über die PHP/cURL-Standardbindungen zum Implementieren der Methoden get(), delete(), post() und put()
  • DefaultConnectionResponse bietet eine einfache Implementierung der Methoden getHttpStatusCode(), getHeaders(), getHeaderValue() sowie getBody() und wird von DefaultConnection verwendet

Was this page helpful?

Do you have any comments?

Thank you for your response.