Java SDK

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:

• Auf alle Funktionen unserer RESTful API auf kompakte, bequeme und anpassbare Weise zugreifen
• Alle serverseitigen Integrationsmodi unserer Plattform nutzen (Hosted Checkout Page / Hosted Tokenization Page / Server-to-server)
• Alle mit der Zahlungsabwicklung zusammenhängenden API-Aufrufe (d. h. CreateHostedCheckout, CreatePayment, RefundPayment und viele mehr) ausführen

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:

• Nutzung von Maven Repository
  Stellen Sie sicher, dass Sie die neueste Version auswählen
  
  
• Nutzung von Gradle
  Stellen Sie sicher, dass Sie die neueste Version auswählen
  
  
• Herunterladen des SDK-Quellcodes von GitHub und manuelle Installation unserer Bibliothek auf Ihrem System

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.

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:

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

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.

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

• Erstellen neuer Transaktionen
• Transaktionsstatus abrufen
• Bearbeitungsfragen durchführen

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

Im Folgenden finden Sie Codebeispiele für bestimmte Integrationsmodi:

• Hosted Checkout Page
• Hosted Tokenization Page
• Server-to-server

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

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.

Hosted Tokenization Page

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

• Eine Vorlage hochladen to your account first. Für Testzwecke können Sie unsere Testvorlage von GitHub nutzen
• Eine CreateHostedTokenizationSession-Anfrage senden

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.

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

Transaktionsstatus abrufen

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

• GetHostedCheckout
• GetPayment
• GetPaymentDetails
• GetCaptures
• GetRefunds

Eine typische GetPayment-Anfrage sieht folgendermaßen aus:

PaymentResponse paymentResponse = merchantClient.payments().getPayment(paymentId);

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

/* 
 *…. 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

/*  
 *…. 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);

/*  
 *… 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);

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.

/*
 * 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); 
} 

/*
 * 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::

/* 
 *…. 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. 
}

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

catch (AuthorizationException e) { 
    System.err.println("Authorization error"); 
    for (APIError error : e.getErrors()) { 
        System.err.println(error.getCode() + ": " + error.getMessage()); 
    }
}

catch (IdempotenceException e) { 
    System.err.println("Idempotence error:"); 
    for (APIError error : e.getErrors()) { 
        System.err.println(error.getCode() + ": " + error.getMessage()); 
    }
}

catch (ReferenceException e) { 
    System.err.println("Incorrect object reference:"); 
    for (APIError error : e.getErrors()) { 
        System.err.println(error.getCode() + ": " + error.getMessage()); 
    }
}

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

catch (ApiException e) { 
    System.err.println("Platform error: "); 
    for (APIError error : e.getErrors()) { 
        System.err.println(error.getCode() + ": " + error.getMessage()); 
    }
}

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.

DeclinedPaymentException

DeclinedPayoutException

DeclinedRefundException

ValidationException

AuthorizationException

ReferenceException

IdempotenceException
ReferenceException

ReferenceException

DirectException

DirectException

DirectException

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
• Senden idempotenter Anfragen
• Protokollierung verwenden
• Pooling von Verbindungen
• Kommunikation individuell einrichten
• Webhooks

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.

/* 
 *…. 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 
}

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)

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

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
  }