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.

Um Zahlungen zu erstellen, müssen Sie Ihren Server mit unserer Plattform über einen unserer Integrationsmodi verknüpfen.

Unsere Java-SDK-Bibliothek ist die ideale Lösung zum Herstellen einer Verbindung zu unserer Plattform, wenn Sie dies lieber mit Ihrem eigenen Standalone-System in der Sprache Java tun möchten.
Wenn Sie das Java SDK wählen, können Sie:

Um die Vorteile dieses SDKs voll ausschöpfen zu können, müssen die folgenden Anforderungen erfüllt sein:

  • Java 8 oder höher
  • Maven/Gradle

Laden Sie die neueste Version der Java-Bibliothek herunter und arbeiten Sie die Installationsanweisungen ab. Sie können die neueste Version des Java SDK hier herunterladen und installieren:

Lesen Sie mehr dazu auf GitHub. Außerdem finden Sie alle verfügbaren SDK-Objekte und -Eigenschaften in unserer vollständigen API-Referenz. Wenn Sie alles vorbereitet haben, sollten Sie die nächsten Kapitel über die Vorbereitung und Verwendung des SDK lesen.

Dieser Leitfaden gibt einen allgemeinen Überblick über die Funktionen des SDK. Um zu sehen, wie sie für die verschiedenen Integrationsmodi genau funktionieren, sollten Sie sich die speziellen Anleitungen ansehen, die jeden Schritt mit vollständigen Codebeispielen erläutern:

Zum Anbinden Ihres Systems mit Hilfe des SDK an unsere Plattform müssen Sie es zunächst initialisieren.

Die Initialisierung umfasst:

  • Ein Test/Live-Konto
  • Erstellung einer Eigenschaftsdatei:
    
    onlinePayments.api.integrator=CompanyName
    onlinePayments.api.endpoint.host=ProperApiEndpoint
     # The properties below are optional and use the given values by default
    onlinePayments.api.endpoint.scheme=https
    onlinePayments.api.endpoint.port=-1
    onlinePayments.api.connectTimeout=10000
    onlinePayments.api.socketTimeout=10000
    onlinePayments.api.maxConnections=10
    onlinePayments.api.https.protocols=TLSv1.2
    onlinePayments.api.authorizationType=V1HMAC
  • Erstellen Sie ein API Key und API Secret für die PSPID, die Sie für die Transaktionsverarbeitung verwenden möchten
  • Initialisieren einer Instanz von Client unter Verwendung von API Key / API Secret zum Einrichten der Anbindung an unsere Test/Live-Plattform

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

Schauen Sie sich Codebeispiele für zwei Verbindungsmethoden für die oben genannten Schritte an:

  1. Mit Hilfe der erstellten Eigenschaftsdatei
    
    private ClientInterface client;
    
    private MerchantClientInterface merchantClient;
    
    public void initialiseSdk () {
     URI propertiesUri = getClass().getClassLoader().getResource("paymentprovider.properties").toURI();
     client = Factory.createClient(propertiesUri, "apiKey", "apiSecret");
     merchantClient = client.merchant("PSPID");
    }
    
  2. Durch die Verwendung von CommunicatorConfiguration
    
    CommunicatorConfiguration communicatorConfiguration =
    
     new CommunicatorConfiguration()
            .withApiKeyId("apiKey")
            .withSecretApiKey("apiSecret")
            .withApiEndpoint(URI.create("apiEndpoint"))
            .withIntegrator("integrator")
            .withAuthorizationType(AuthorizationType.V1HMAC);
    client = Factory.createClient(communicatorConfiguration);
    clientMerchant = client.merchant("PSPID");
    

Die folgende Tabelle enthält einen Überblick über die von den einzelnen Instanzen akzeptierten Argumente:

Eigenschaften
  • string merchantId: Ihre PSPID entweder in unserer Test/Live-Umgebung. Vergewissern Sie sich, dass Sie für Ihre Transaktionsanfrage das richtige API Key / API Secret-Paar zusammen mit der dazugehörigen PSPID verwenden
  • string apiKey: Der API Key, den Sie in Ihrer PSPID definiert haben und an den Sie die Transaktionen senden werden
  • string apiSecret: Das API Secret, das Sie in Ihrer PSPID definiert haben und an das Sie die Transaktionen senden werden

    Schauen Sie sich unseren entsprechenden Leitfaden an. Dort erfahren Sie alles über API Key / API Secret

  • string apiEndpoint: Er enthält einen Link entweder zu unserer Test oder Live-Umgebung, an die Ihre Transaktionsanfragen gesendet werden

Der vollständige Pfad des API-Endpunkts für die Test-/Live-Umgebung lautet jeweils

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

Da unsere SDKs immer die neuste Version unserer API implementieren, können Sie "v2" in Ihrem Code auslassen so wie hier dargestellt.

  • 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, nutzen. Wir empfehlen daher dringend das Senden eines Wertes, mit dem wir Ihre Anfragen in unseren Protokollen leicht identifizieren können

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 erhalten Sie vollen Zugang zu unserer RESTful-API. Dort können Sie Folgendes durchführen:

  • Anfragen für neue Transaktionen für jeden unserer Server-Integrationsmodi senden
  • Den aktuellen Status Ihrer Transaktionen abrufen
  • Bearbeitungsanfragen (z. B. Zahlungserfassungen, 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

Schauen Sie sich unsere Testszenarien auf GitHub an, einschließlich vollständiger Codebeispiele, und unsere vollständige API-Referenz an. Dort erfahren Sie, was alles möglich ist.

IClient implementiert die IDisposable-Schnittstelle, sodass Sie diesen in using-Anweisungen verwenden können. Dies gibt Ressourcen frei, wenn sie nicht mehr benötigt werden. Alternativ dazu empfehlen wir dringend ein manuelles Schließen der Verbindung.

ClientInterface erweitert die java.io.Closable-Schnittstelle, sodass Sie dieses in try-with-resources-Anweisungen verwenden können. Dies gibt Ressourcen frei, wenn sie nicht mehr benötigt werden. Alternativ dazu empfehlen wir dringend ein manuelles Schließen der Verbindung

client.closeIdleConnections(30, TimeUnit.MINUTES);

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

Erstellen neuer Transaktionen

Zum Erstellen einer neuen Transaktion können Sie die Client-oder MerchantClient-Instanz für einen unserer Integrationsmodi verwenden. Dies ist möglich durch:

  • Weiterleitung der Anfrage an Ihre PSPID auf unserer Plattform (für Client)
  • Erstellen eines Antrags für den jeweiligen Integrationsmodus

Die SDK-Instanz speichert nur die zu ihrer Initialisierung verwendeten Daten. Es werden weder aktive Sitzungen noch frühere Anfragen verfolgt. Ihr System ist verantwortlich für die Verwaltung von Direct-Sitzungen und -Zahlungen
Sitzungen und Zahlungen wirken sich nicht auf andere Sitzungen und Zahlungen aus

Im Folgenden finden Sie Codebeispiele für bestimmte Integrationsmodi:

Hosted Checkout Page

Um diesen Integrationsmodus nutzen zu können, müssen Sie einen CreateHostedCheckoutRequest-Aufruf erstellen. Dieser muss mindestens ein Order-Objekt enthalten.


/* 
 *…. Initialisation....
 */

// The example object of the AmountOfMoney 
AmountOfMoney amount = new AmountOfMoney()
.withAmount(100L)
.withCurrencyCode("EUR");
checkoutRequest.withOrder(new Order().withAmountOfMoney(amount));
CreateHostedCheckoutResponse response = hostedCheckoutClient.createHostedCheckout(checkoutRequest);
Sie können eine optionale returnUrl angeben, die Ihren Kunden zurück auf Ihre Website führt

Dieser Aufruf gibt eine CreateHostedCheckout-Antwort zurück. Speichern Sie die hostedCheckoutId und RETURNMAC sowie alle anderen für Sie relevanten Informationen. Sie benötigen diese 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 gemäß folgender Formel verketten

https://payment. + partialRedirectURL

und Ihren Kunden zu dieser URL weiterleiten. Sobald der Kunde auf die Website Hosted Checkout Page gelangt, wird das Zahlungsverfahren dort fortgesetzt.

Die neueste Version unseres SDKs gibt auch den vollständigen Pfad in redirectURL zurück, sodass Sie die Verkettung der Basis-URL „https://payment.“ mit partialRedirectURL überspringen können. Weitere Informationen finden Sie in unserem Hosted Checkout Page-Leitfaden. 

Hosted Tokenization Page

Um diese Integrationsmethode verwenden zu können, müssen Sie

CreateHostedTokenizationRequest hostedTokenizationRequest = new CreateHostedTokenizationRequest();
CreateHostedTokenizationRequest createHostedTokenizationRequest =
hostedTokenizationRequest.withVariant("YourTemplate.html");
CreateHostedTokenizationResponse hostedTokenizationResponse = merchantClient.hostedTokenization()
.createHostedTokenization(createHostedTokenizationRequest);


Von CreateHostedTokenizationResponse müssen Sie hostedTokenizationId und partialRedirectUrl abrufen. Nutzen Sie partialRedirectUrl für das iframe und die hostedTokenizationId oder tokenId (siehe Infobox) um die eigentliche Zahlung via Server-to-server zu erstellen.

Sie können entweder tokenID oder die hostedTokenizationId in Ihrere CreatePayment-Anfrage senden. Lernen Sie mehr dien entsprechenden Kapiteln in unserem Hosted Tokenization Page-Leitfaden:

GetHostedTokenizationResponse getHostedTokenizationResponse = initializer.getClientMerchant().hostedTokenization().getHostedTokenization(hostedTokenizationId);
String tokenId = getHostedTokenizationResponse.getToken().getId();

// The example object of the AmountOfMoney 
AmountOfMoney amount = new AmountOfMoney() 
      .withAmount(100L) 
      .withCurrencyCode("EUR"); 

Order order = new Order().withAmountOfMoney(amount);
CardPaymentMethodSpecificInput paymentInput = new CardPaymentMethodSpecificInput().withToken(tokenId);

CreatePaymentRequest requestBody = new CreatePaymentRequest()
        .withCardPaymentMethodSpecificInput(paymentInput)
        .withOrder(order);
CreatePaymentResponse response = initializer.getClientMerchant().payments().createPayment(requestBody);

Server-to-server

Eine minimale paymentResponse erfordert, dass Sie mindestens ein Order-Objekt und eine Zahlungsart festlegen:


// The example object of the AmountOfMoney 

AmountOfMoney amountOfMoney = new AmountOfMoney() 
        .withAmount(100L) 
        .withCurrencyCode("EUR"); 
Order order = new Order().withAmountOfMoney(amountOfMoney); 
 
// To get more test card data visit the website: Find more test data here 
Card card = new Card() 
         .withCvv("123") 
         .withCardNumber("5399999999999999") 
         .withCardholderName("Test Name") 
         .withExpiryDate("1236"); 
int paymentProductId = 3; 
 
PaymentsClientInterface paymentClient = merchantClient.payments(); 
CreatePaymentRequest createPaymentRequest = new CreatePaymentRequest(); 
 
CardPaymentMethodSpecificInput cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput(); 
cardPaymentMethodSpecificInput.setCard(card); 
cardPaymentMethodSpecificInput.setPaymentProductId(paymentProductId) ; 
 
createPaymentRequest.setCardPaymentMethodSpecificInput(cardPaymentMethodSpecificInput); 
createPaymentRequest.setOrder(order); 
 
CreatePaymentResponse createPaymentResponse = paymentClient.createPayment(createPaymentRequest);

Für jeden der oben genannten Integrationsmodi gibt es einen eigenständigen Leitfaden:

Die Dokumente enthalten alle wichtigen Details, die Sie benötigen, um das volle Potenzial der Integrationsmodi einschließlich vollständiger Transaktionsabläufe, Codebeispiele und anderer nützlicher Funktionen nutzen zu können.

Transaktionsstatus abrufen

Unsere RESTful API ermöglicht es Ihnen, den Status einer Transaktion jederzeit mit einem unserer GET -Aufrufe anzufordern:

Eine typische GetPayment-Anfrage sieht folgendermaßen aus:


PaymentResponse paymentResponse = merchantClient.payments().getPayment(paymentId);
Eigenschaften
string paymentId: Die eindeutige Referenz für Ihre Transaktion auf unserer Plattform. Diese Referenz ist von CreatePaymentResponse oder createHostedCheckoutResponse abrufbar, die im vorherigen Abschnitt erstellt wurde.

Weitere Informationen zu Statifinden Sie auf der Status-Dokumentationsseite.

Bearbeitungsanfragen durchführen

Zum Durchführen von Folgeaktionen zu bestehenden Transaktionen (z. B. Erfassungen oder Erstattungen) können Sie unseren CapturePayment bzw. RefundPayment API-Aufruf nutzen:

CapturePayment

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • CapturePaymentRequest

/* 
 *…. Initialisation....
 */
MerchantClientInterface merchantClient;

// Here you get paymentId you can use in further code
String paymentId = createPaymentResponse.getPayment().getId();
CapturePaymentRequest capturePaymentRequest = new CapturePaymentRequest();
capturePaymentRequest.withAmount(amount);
capturePaymentRequest.setIsFinal(true);

merchantClient.payments().capturePayment(paymentId, capturePaymentRequest);

RefundPayment

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • RefundRequest
  • AmountOfMoney
/*  
 *…. Initialisation.... 
 */ 
 
MerchantClientInterface merchantClient;

String paymentId;

RefundRequest refundRequest = new RefundRequest();

// The example object of the AmountOfMoney
AmountOfMoney amountOfMoney = new AmountOfMoney()
.withAmount(100L)
.withCurrencyCode("EUR");
refundRequest.setAmountOfMoney(amountOfMoney);

// Get RefundResponse object
RefundResponse refundResponse = merchantClient.payments().refundPayment(paymentId, refundRequest);
Eigenschaften
string paymentId: Die eindeutige Referenz für Ihre Transaktion auf unserer Plattform. Diese Referenz ist von CreatePaymentResponse oder createHostedCheckoutResponse abrufbar, die im vorherigen Abschnitt erstellt wurde.

Achten Sie darauf, dass Sie die folgenden Klassen verwenden:

  • RefundRequest
  • AmountOfMoney
/*  
 *… Initialisation.... 
 */ 
MerchantClientInterface merchantClient;
String paymentId;
RefundRequest refundRequest = new RefundRequest();
// The example object of the AmountOfMoney
AmountOfMoney amountOfMoney = new AmountOfMoney()
        .withAmount(100L)
        .withCurrencyCode("EUR");
refundRequest.setAmountOfMoney(amountOfMoney);
// Get RefundResponse object
RefundResponse refundResponse = merchantClient.payments().refundPayment(paymentId, refundRequest);
Properties
string paymentId: Die eindeutige Referenz für Ihre Transaktion auf unserer Plattform. Diese Referenz ist von CreatePaymentResponse oder createHostedCheckoutResponse abrufbar, die im vorherigen Abschnitt erstellt wurde.

Bei Ablehnung einer Transaktion liefert unsere Plattform detaillierte Informationen mit einer Exception-Instanz. Der dazugehörige HTTP status-Code hilft Ihnen ebenfalls bei der Fehlersuche.

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

Transaktionsausnahmen

Diese Art Ausnahme bezieht sich auf Transaktionsanfragen, die systemtechnisch korrekt sind, aber vom Emittenten Ihres Kunden oder Ihrem Acquirer abgelehnt wurden. Wenn die Transaktion in der Ausnahme zurückgegeben wird, bedeutet dies, dass sie in unseren Systemen erstellt, aber nicht erfolgreich verarbeitet wurde.

Die folgenden Codebeispiele nutzen implizite Methoden, die als Beispiel dienen. Es wird von Ihnen erwartet, dass Sie diese selbst implementieren oder durch eine ähnliche Logik ersetzen.
Ausnahmetyp /
HTTP-Statuscode Codebeispiel
Codebeispiel
Abgelehnte Transaktionen /
Verschiedenes (siehe PaymentResponse-Objekt)

/*
 * Initialization....
 */


CreatePaymentRequest createPaymentRequest = new CreatePaymentRequest();
String paymentId;
try {
CreatePaymentResponse createPaymentResponse = paymentClient.createPayment(createPaymentRequest);
paymentId = createPaymentResponse.getPayment().getId();
} catch (DeclinedPaymentException e) {

PaymentResponse payment = e.getCreatePaymentResult().getPayment();
paymentId = payment.getId();
String paymentStatus = payment.getStatus();
handleError(payment);
}
PaymentResponse paymentResponse = merchantClient.payments().getPayment(paymentId);

// Your code to check transaction status and handle errors
if (isNotSuccessful(paymentResponse)) {
handleError(paymentResponse);
}
Abgelehnte Gutschriften /
Verschiedenes (siehe PaymentResponse-Objekt)
/*
 * Initialization....
 */


String paymentId = createPaymentResponse.getPayment().getId();
String refundId;

RefundRequest refundRequest = new RefundRequest();

try {
RefundResponse refundResponse = merchantClient.payments().refundPayment(paymentId, refundRequest);
refundId = refundResponse.getId();
} catch (DeclinedRefundException e) {
RefundResponse refundResult = e.getRefundResult();
handleError(refundResult);
}
RefundsResponse refundResponse = merchantClient.payments().getRefunds(paymentId);

// Your code to check transaction status and handle errors
if (isNotSuccessful(refundResponse, refundId)) {
handleError(refundResponse);
}

$refundResponse = $merchantClient
->payments()
->refundPayment($paymentID, $refundRequest);

// Your code to check transaction status and
// handle errors
if (isNotSuccessful($refundResponse, $refundID)) {
handleError($refundResponse);
}

HTTP-Ausnahmen

Diese Art Ausnahme bezieht sich auf verschiedene Probleme, die durch technische Fehler beim API-Aufruf oder bei der Zahlungsanforderung verursacht werden.

Sie können jeden der folgenden Codefragmente mit dieser CreatePayment-Standardanfrage kombinieren::

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

/* 
 *…. Initialisation....
 */

CreatePaymentRequest createPaymentRequest = new CreatePaymentRequest(); 

// The example object of the AmountOfMoney
AmountOfMoney amountOfMoney = new AmountOfMoney()
.withAmount(100L)
.withCurrencyCode("EUR");

Order order = new Order().withAmountOfMoney(amountOfMoney);

CardPaymentMethodSpecificInput cardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput();

// The example object of the Card – you can find test cards on
// /documentation/test-cases/
Card card = new Card()
.withCvv("123")
.withCardNumber("5399999999999999")
.withCardholderName("Test Name")
.withExpiryDate("1236");

cardPaymentMethodSpecificInput.setCard(card);
cardPaymentMethodSpecificInput.setPaymentProductId(3);

createPaymentRequest.setCardPaymentMethodSpecificInput(cardPaymentMethodSpecificInput);

try {
CreatePaymentResponse createPaymentResponse = paymentClient.createPayment(createPaymentRequest);
}
catch (ApiException e) {
// Refer to the list below to see how specific implementations of ApiException can be handled.
}
Ausnahmetyp /
HTTP-Statuscode
Codebeispiel
ValidationException /
400
catch (ValidationException e) { 
System.err.println("Input validation error");
for (APIError error : e.getErrors()) {
if (error.getPropertyName() == null) {
System.err.println(error.getCode() + ": " + error.getMessage());
} else {
System.err.println(error.getPropertyName() + ": " + error.getCode() + ": " + error.getMessage());
}
}
}
AuthorizationException /
403
catch (AuthorizationException e) { 
System.err.println("Authorization error");
for (APIError error : e.getErrors()) {
System.err.println(error.getCode() + ": " + error.getMessage());
}
}
IdempotenceException /
409
catch (IdempotenceException e) { 
System.err.println("Idempotence error:");
for (APIError error : e.getErrors()) {
System.err.println(error.getCode() + ": " + error.getMessage());
}
}
ReferenceException /
404/409/410
catch (ReferenceException e) { 
System.err.println("Incorrect object reference:");
for (APIError error : e.getErrors()) {
System.err.println(error.getCode() + ": " + error.getMessage());
}
}
DirectException /
500/502/503
catch (DirectException e) { 
System.err.println("Error occurred at Direct or a downstream partner/acquirer:");
for (APIError error : e.getErrors()) {
System.err.println(error.getCode() + ": " + error.getMessage());
}
}
ApiException /
Alle anderen Statuscodes
catch (ApiException e) { 
System.err.println("Platform error: ");
for (APIError error : e.getErrors()) {
System.err.println(error.getCode() + ": " + error.getMessage());
}
}
CommunicationException /
300er-Codes ohne Anfrageinhalt oder Antwort nicht im JSON-Format
catch (CommunicationException e) { 
System.err.println("Communication exception: " + e.getMessage());
}

HTTP-Statuscodes

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

Statuscode Beschreibung Ausnahmetyp
200

Successful
Unsere Plattform hat Ihre Anfrage ordnungsgemäß bearbeitet

-
201

Created
Unsere Plattform hat Ihre Anfrage ordnungsgemäß bearbeitet und eine neue Ressource erstellt. Wir geben den URI dieser Ressource in der Header-Location der Antwort zurück

-
204

No content
Unsere Plattform hat Ihre Anfrage ordnungsgemäß bearbeitet

-
Verschiedenes
paymentResult-Schlüssel ist in der Antwort

Payment Rejected
Entweder unsere Plattform oder einer unserer nachgelagerten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedPaymentException
Verschiedenes
payoutResult-Schlüssel ist in der Antwort

Payout Rejected
Entweder unsere Plattform oder einer unserer nachgelagerten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedPayoutException

Verschiedenes
refundResult-Schlüssel ist in der Antwort

Refund Rejected
Entweder unsere Plattform oder einer unserer nachgelagerten Partner/Acquirer hat Ihre Anfrage abgelehnt

DeclinedRefundException
400

Bad Request
Ihre Anfrage enthält Fehler, daher kann unsere Plattform diese nicht bearbeiten

ValidationException
403

Not Authorised
Sie versuchen, etwas zu tun, was nicht erlaubt ist, oder wozu Sie nicht befugt sind

AuthorizationException
404

Not Found
Das Objekt, auf das Sie zugreifen wollten, wurde auf dem Server nicht gefunden

ReferenceException
409

Conflict
Ihre idempotente Anfrage führte zu einem Konflikt, weil eine der folgenden Ausnahmen eingetreten ist:

  • Die erste Anfrage ist noch nicht abgeschlossen
  • Ihre Anfrage führte zu einem Konflikt. Entweder haben Sie eine doppelte Anfrage gestellt, oder Sie versuchen, etwas mit einem doppelten Schlüssel zu erstellen

IdempotenceException
ReferenceException

410

Gone
Das Objekt, auf das Sie zugreifen wollen, ist entfernt worden.

ReferenceException
500

Internal Server Error
Auf unserer Plattform ist ein Fehler aufgetreten

DirectException
502 Bad Gateway
Unsere Plattform war nicht in der Lage, eine Nachricht von einem nachgeschalteten Partner/Acquirer zu verarbeiten
DirectException
503 Service Unavailable
Der Dienst, den Sie erreichen möchten, ist vorübergehend nicht verfügbar. Bitte versuchen Sie es später noch einmal
DirectException
Other Unexpected error
Es ist ein unerwarteter Fehler aufgetreten
ApiException

Das SDK hat noch viel mehr zu bieten. Schauen Sie sich die folgenden Merkmale an, denn diese helfen Ihnen beim Finden der perfekten Lösung.

Verfügbare Zahlungsarten abrufen

Vor dem Einleiten des eigentlichen Zahlungsverfahrens müssen Sie eine GetPaymentProducts Anfrage an unsere Plattform senden. Die Antwort enthält eine Liste der in Ihrer PSPID verfügbaren Zahlungsarten. Je nach Vorlieben Ihrer Kunden können Sie eine Auswahl auf unserer Hosted Checkout Page oder Ihrer eigenen Webshop-Umgebung mit nachfolgenden CreatePayment-Anfragen anbieten.

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

/* 
 *…. Initialisation....
 */

// Prepare the request to get all active payment methods in your PSPID 
var queryParams = new GetPaymentProductsParams()
.withCountryCode("FR")
.withCurrencyCode("EUR");

// Send the request and get the response
GetPaymentProductsResponse paymentProductResponse = merchantClient.products().getPaymentProducts(queryParams);

Senden idempotenter Anfragen

Eines der wichtigsten Merkmale der REST-API ist die Fähigkeit zum Erkennen und Verhindern versehentlich doppelt gesendeter Anfragen (z. B. Zahlungsanfragen). Das SDK macht es Ihnen sehr leicht, sicherzustellen, dass Sie nur einmalige – idempotente – Anfragen an unsere Plattform senden.

Verwenden Sie das zusätzliche Argument paymentContext und setzen Sie dessen Eigenschaft namens idempotence auf eine CreatePayment-Anfrage. 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 nachfolgende Anfrage mit demselben Idempotence-Schlüssel senden, enthält die Antwort inen X-GCS-Idempotence-Key-Header. Das SDK setzt die idempotenceRequestTimestamp -Eigenschaft des paymentContext -Arguments
  • Wenn die erste Anfrage noch nicht abgeschlossen ist, gibt die RESTful Server API den Statuscode 409 zurück. Dann gibt das SDK eine IdempotenceException mit dem ursprünglichen Idempotence-Schlüssel und dem Zeitstempel der Idempotence-Anforderung aus

/* 
 *…. Initialisation....
 */

CreatePaymentRequest createPaymentRequest = new CreatePaymentRequest(); 

String idempotenceKey = "YourKeyForThePayment";

var callContext = new CallContext();
callContext.withIdempotenceKey(idempotenceKey);

try {
var createPaymentResponse = merchantClient.payments().createPayment(createPaymentRequest, callContext);
} catch (IdempotenceException e) {
// a request with the same idempotenceKey is still in progress, try again after a short pause
// e.getIdempotenceRequestTimestamp() contains the value of the
// X-GCS-Idempotence-Request-Timestamp header
} finally {
Long idempotenceRequestTimestamp = callContext.getIdempotenceRequestTimestamp();
// idempotenceRequestTimestamp contains the value of the
// X-GCS-Idempotence-Request-Timestamp header
// if idempotenceRequestTimestamp is not empty, this was not the first request
}
Wenn ein Idempotence-Schlüssel für einen Aufruf gesendet wird, der keine Idempotenz 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 Ausnahmen der API-Kommunikation. Diese können bei Fehlersuche oder Nachverfolgung einzelner Schritte im Zahlungsfluss hilfreich sein.

Um die Protokollierungsfunktion nutzen zu können, muss eine Implementierung der CommunicatorLogger-Schnittstelle vorliegen..

Das SDK bietet zwei Implementierungen der Protokollierungsfunktion:

  • System.out (SysOutCommunicatorLogger)
  • java.util.logging.Logger (JdkCOmmunicatorLogger)
Achten Sie darauf, dass Sie die folgenden Klassen verwenden:
  • ResourceLogger

Sie können die Protokollierung aktivieren/deaktivieren, indem Sie die enableLogging-Methode auf einem ClientInterface-Objekt aufrufen und den Logger als Argument angeben. Der Logger lässt sich nachträglich durch Aufrufen der Methode disableLogging deaktivieren:


ClientInterface client = Factory.createClient(propertiesUrl.toURI(), "apiKeyId", "secretApiKey");

CommunicatorLogger logger = new JdkCommunicatorLogger(Logger.getLogger(...), Level.INFO);
client.enableLogging(logger);
//... Do some calls
client.disableLogging();
Das SDK verbirgt sensible Daten im Logger

Pooling von Verbindungen

Sie können Ihre Netzwerkressourcen verwalten, indem Sie die Anzahl der möglichen Verbindungen begrenzen, die das SDK erstellt und aufrechterhält. Die Client-Instanzen, die im Abschnitt SDK-Kapitel initialisieren beschrieben wurden, haben ihren eigenen Verbindungspool. Die Client-Instanzen, die mit demselben Communicator-Objekt erstellt wurden, teilen sich einen Verbindungspool.

Wenn Sie mehrere Client-Instanzent verwenden, um einen einzigen Verbindungspool gemeinsam zu nutzen, müssen Sie die folgenden Schritte befolgen:

  1. Erstellen Sie einen freigegebenen Communicator . Dazu können Sie die com.onlinepayments.Factory-Klasse verwenden
  2. Erstellen Sie Client-Instanzen mit diesem Communicator

/* 
 *…. Initialisation....
 */

/* Initialisation... */  
// Communicator instance
Communicator communicator = Factory.createCommunicator(propertiesUrl.toURI(), "apiKeyId", "secretApiKey");
// create one or more clients using the shared communicator
ClientInterface client = Factory.createClient(communicator);

Kommunikation individuell einrichten

Ein ClientInterface nutzt zum Kommunizieren mit unserer Plattform einen Communicator. Communicator-Implementierungen wandeln ein Anfrageobjekt in eine HTTP-Anfrage und eine HTTP-Antwort in ein Antwortobjekt um. Bei Bedarf können Sie diese Klasse erweitern. Zum Instanziieren eines ClientInterface , mit Ihrer eigenen Implementierung von Communicator können Sie das folgende Codefragment verwenden:


Communicator communicator = new YourCommunicator();
ClientInterface client = Factory.createClient(communicator);

Die Bereitstellung einer eigenen Implementierung ist in den meisten Fällen nicht erforderlich. Die Funktionalität des com.onlinepayments.defaultimpl.DefaultCommunicator ist auf Klassen aufgebaut: Authenticator, Connection, Marshaller und MetaDataProvider. Die Implementierung dieser Klassen lässt sich leicht erweitern oder ersetzen, um Ihren Bedürfnissen gerecht zu werden.

Ein Marshaller wird verwendet, um das Marshalling/Unmarshalling auf Request- und Response-Objekte in und aus JSON anzuwenden.Dies sollten Sie nicht ändern. Die für die Kommunikation mit unserer Plattform benötigten weiteren Module sind:

  • Die RESTful Server API Endpunkt-URI
  • Eine Connection für eine oder mehrere HTTP-Verbindungen zu unserem Server
  • Ein Authenticator zum Signieren Ihrer Anfragen
  • Ein MetaDataProvider, der den Header mit den Metadaten Ihres Servers erstellt

Der Einfachheit halber wird die CommunicatorBuilder-Klasse zur Verfügung gestellt, mit der Sie eines oder mehrere dieser Module leicht ersetzen können. Beispiel: Zum Instanziieren eines ClientInterface das Ihre eigene Implementierung von Connection verwendet, können Sie das folgende Codefragment verwenden:


/* 
 *…. Initialisation....
 */

Connection connection = new YourConnection();  
Communicator communicator = Factory.createCommunicatorBuilder(propertiesUrl.toURI(), "apiKeyId", "secretApiKey").withConnection(connection).build();
ClientInterface client = Factory.createClient(communicator);

Webhooks

Der für den Webhooks-Support zuständige Teil des SDK heißt Webhooks Helper. Er übernimmt transparent sowohl die Validierung von Signaturen gegen die vom Webhooks-System gesendeten Ereignistexte (einschließlich der Ermittlung des secret key für key IDs – nicht zu verwechseln mit dem API Key /API Secret), und das Unmarshalling dieser Texte zu Objekten. So können Sie sich auf das Wesentliche konzentrieren, ohne all die zusätzlichen Informationen durchgehen und die gewünschten Informationen selbst extrahieren zu müssen. Um mehr über Webhooks zu erfahren, esen Sie unseren eigenständigen Leitfaden. 

Bereitstellen der secret keys

Konfigurieren Sie den "WebhooksKey" / "WebhooksKeySecret" und Ihren Server-Webhooksendpoint im Merchant Portal:


String keyId = "WebhooksKey";
String secretKey = "WebhooksKeySecret";

Verwenden Sie InMemorySecretKeyStore.INSTANCE.storeSecretKey(keyId, secretKey) zum Speichern eines secret key für eine key ID.

Sie können mit den folgenden Funktionen Tasten hinzufügen oder entfernen:

  • InMemorySecretKeyStore.INSTANCE.getSecretKey(keyId)
  • InMemorySecretKeyStore.INSTANCE.removeSecretKey(keyId) zum Entfernen des gespeicherten secret key für eine key ID
  • InMemorySecretKeyStore.INSTANCE.clear() zum Entfernen aller gespeicherten secret keys

Wenn Sie eine erweiterte Speicherung benötigen, z. B. mit einer Datenbank oder einem Dateisystem, empfehlen wir Ihnen das Schreiben Ihrer eigenen Implementierung. 

Webhooks Helper initialisieren

Mit einer Implementierung von com.onlinepayments.webhooks.SecretKeyStore erzeugen Sie eine Instanz von  com.onlinepayments.webhooks.WebhooksHelper:


WebhooksHelper helper = Webhooks.createHelper(InMemorySecretKeyStore. INSTANCE);

Webhook Helper verwenden

Um von einem Webhook empfangene Ereignisse zu verarbeiten, müssen Sie zunächst die unmarshal-Methode des WebhooksHelper-Objekts aufrufen. Sie akzeptiert die folgenden Argumente:

  • Der Text in Form einer Zeichenfolge. Dies sollte der Rohtext sein, wie er vom Webhooks-System empfangen wird:

    String bodyOfRequest = "JSON_Body_Of_The_Request";
  • Eine Liste der vom Webhooks-System empfangenen Anfrage-Header. Nachstehend finden Sie ein Beispiel zum Erstellen einer Liste von Anforderungs-Headers. Sie sollte zwei Header enthalten – für keyId und für signature:

    // Retrieve the headers from the Webhook message, depends on your implementation.
    List<Header> webhookHeaders = request.getHeaders();
    
    // Transform the received headers
    List<RequestHeader> requestHeaders = new ArrayList<RequestHeader>();
    for (Header webhookHeader : webhookHeaders) {
        requestHeaders.add(new RequestHeader(webhookHeader.getName(), webhookHeader.getValue()));
    }
  • Jetzt können Sie einen Webhooks Helper für das Unmarshalling eingehender Ereignisse nutzen, mit denen Sie Daten in Ihrer Anwendung verarbeiten können:

    try {
        WebhooksEvent event = helper.unmarshal(bodyOfRequest, requestHeaders);
    } catch (SignatureValidationException e) {
        // Your code to handle error
    }
    

Was this page helpful?

Do you have any comments?

Thank you for your response.