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.
Unser .NET SDK ist die ideale Lösung zur Verbindung mit unserer Plattform, wenn Sie es vorzugsweise mit Ihrem eigenständigen System in der Sprache C# tun möchten. 

Durch Auswahl des .NET SDK können Sie:

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

  • .NET Framework 4.5 / .NET Standard 2.0 oder 2.1
  • IDE: Visual Studio 2019
  • Plattform: Windows

Nähere Einzelheiten zu diesen Anforderungen finden Sie auf GitHub. Sehen Sie sich auch alle verfügbaren SDK-Objekte und -Eigenschaften in unserer vollständigen API-Referenz an.

Laden Sie die neueste Version herunter und gehen Sie nach der Installationsanleitung vor. 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:

Um das SDK für die Verbindung Ihres Systems mit unserer Plattform zu nutzen, 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 erstellen, die Sie für die Transaktionsverarbeitung verwenden möchten
  • Eine Instanz von IClient 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:


// Das Feld IClient für die SDK-Initialisierung und zur späteren Verwendung deklarieren.
private IClient client;

// Falls Sie eine PSPID verwenden, deklarieren Sie das Feld IMerchantClient.
private IMerchantClient merchantClient;

public void SetupDirectSDK()
{
	// Einen URI für unsere Test- oder Live-Umgebung einrichten
	Uri apiEndpoint = new Uri("https://payment.preprod.direct.worldline-solutions.com/");

	// Clients mit URI und API-Schlüssel/API-Geheimnis aus Ihrer PSPID initialisieren		
	client = Factory.CreateClient(apiKey, apiSecret, apiEndpoint, integrator);

	// Falls Sie mehrere PSPIDs haben, ersetzen Sie bitte den merchantClient in den folgenden Beispielen durch dieses Code-Beispiel: 
	merchantClient = client.WithNewMerchant(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


  • Uri apiEndpoint: Ihre Transaktionsanfragen an unsere Test- oder Live-Umgebung senden

Eine Client-Instanz können Sie für verschiedene Aufrufe wiederverwenden. Sie können verwenden:

  • Den IMerchantClient, der im Beispiel für alle Aufrufe für diese PSPID initialisiert wurde.
  • Die IClient-Instanz zum Erzeugen von IMerchantClients für verschiedene (oder dieselben) PSPIDs.

Sie können auch für jeden Aufruf eine neue Instanz erstellen, aber das verbraucht nur unnötig weitere Systemressourcen

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

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 IClient-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 (Erfassungen, Gutschriften etc.) 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.

IClient implementiert die Schnittstelle IDisposable, die Sie in using-Anweisungen verwenden können. Dadurch werden Ressourcen freigegeben, wenn sie nicht mehr benötigt werden. Alternativ dazu empfehlen wir dringend, die Verbindung manuell zu schließen:

client.CloseIdleConnections(yourTimespan)

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 IMerchantClient- oder IClient-Instanz für einen unserer Integrationsmodi verwenden. Dazu können Sie:

  • die Anfrage an Ihre PSPID auf unserer Plattform (für IClient) 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.


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

private CreateHostedCheckoutRequest createHostedCheckoutRequest = new CreateHostedCheckoutRequest { Order = new Order { AmountOfMoney = new AmountOfMoney { Amount = 100, CurrencyCode = "EUR" } } }; // IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden var createHostedCheckoutResponse = await merchantClient .HostedCheckout .CreateHostedCheckout(createHostedCheckoutRequest);

Auf Wunsch können Sie eine returnUrl angeben, die dafür verwendet wird, Ihren Kunden zurück zu Ihrer Website zu leiten

Diese Anfrage gibt eine CreateHostedCheckoutResponse-Antwort zurück. 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:


private CreateHostedTokenizationRequest createHostedTokenizationRequest = new CreateHostedTokenizationRequest();

// Felder für eine minimale CreateHostedTokenizationRequest initialisieren 
createHostedTokenizationRequest.Variant = “my-custom-template.html”;


// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden
var createHostedTokenizationResponse = await merchantClient
    .HostedTokenization
    .CreateHostedTokenization(createHostedTokenizationRequest);

Rufen Sie aus CreateHostedTokenizationResponse hostedTokenizationId und 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:


// Ergebnis der Tokenisierungssitzung abrufen
var getHostedTokenizationResponse = await client
	.WithNewMerchant("IhrePSPID")
	.HostedTokenization
	.GetHostedTokenization(createHostedTokenizationResponse.HostedTokenizationId);

// tokenId abrufen, die für die Zahlungserstellung verwendet werden soll
var tokenId = getHostedTokenizationResponse.Token.Id;
CreatePaymentRequest requestBody = new CreatePaymentRequest
{
	CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
	{
		Token = tokenId // Durch Aufruf von GetHostedTokenization() empfangenes Token
	},
	Order = new Order
	{
		AmountOfMoney = new AmountOfMoney
		{
			Amount = 100, // Der Betrag, den Sie Ihrem Kunden berechnen möchten, multipliziert mit 100 (1,00 EUR)
			CurrencyCode = "EUR"
		}
	}
};

var response = await client
	.WithNewMerchant("IhrePSPID")
	.Payments
	.CreatePayment(requestBody);

Server-to-server

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


// Felder für eine minimale CreatePaymentResponse initialisieren
CreatePaymentRequest body = new CreatePaymentRequest
{
    Order = new Order
    {
        AmountOfMoney = new AmountOfMoney
            {
                Amount = 100,
                CurrencyCode = "EUR"
            }
    },
    CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput // Mehr Testdaten finden Sie hier 
    {
        Card = new Card
        {
            CardholderName = "Wile E. Coyote",
            CardNumber = "4111111111111111",
            Cvv = "123",
            ExpiryDate = "1236"
        }
    }
};



// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden
var createPaymentResponse = await merchantClient
    .Payments
    .CreatePayment(body);

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:

// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden
PaymentResponse paymentResponse = await MerchantClient
.Payments
.GetPayment(paymentID);
Eigenschaften
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ßnahmen 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


CapturePaymentRequest body = new CapturePaymentRequest
{
    Amount = 100,
    IsFinal = true
};

// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden
CaptureResponse captureResponse = await merchantClient
    .Payments
    .CapturePayment(paymentId, body);

RefundPayment


RefundRequest body = new RefundRequest

AmountOfMoney = new AmountOfMoney
{
       	Amount = 100,
CurrencyCode = "EUR"
    
};

// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden
RefundResponse refundRespsonse = await merchantClient
    .Payments
    .RefundPayment(paymentId, body);
Eigenschaften
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 von 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 angegeben sind. Von Ihnen wird erwartet, dass Sie diese Methoden selbst implementieren oder durch eine vergleichbare Logik ersetzen
Ausnahmetyp /
HTTP-Statuscode
Code-Beispiel
Abgelehnte Transaktionen /
Verschiedenes (siehe Objekt PaymentResponse)
CreatePaymentRequest body = CreateRequest();
string paymentId; try
{
CreatePaymentResponse response = await merchantClient .Payments .CreatePayment(body);
paymentId = response.Payment.Id;
}
catch (DeclinedPaymentException e)
{
PaymentResponse payment = e.CreatePaymentResponse.Payment;
paymentId = payment.Id;
System.Console.WriteLine(e.Message);
foreach (APIError error in e.Errors)
{
System.Console.WriteLine("Fehler {0}: {1}, {2}", error.Code, error.Id, error.Message);
}
}
PaymentResponse paymentResponse = await MerchantClient .Payments .GetPayment(paymentId);
if (IsNotSuccessful(payment))
{
HandleError(payment);
}
Abgelehnte Gutschrift /
Verschiedenes (siehe Objekt PaymentResponse)
RefundRequest body = createRequest();

String refundId;
try
{
RefundResponse response = await merchantClient .Payments .RefundPayment("PayID", body);
refundId = response.Id;
}
catch (DeclinedRefundException e)
{
RefundResponse refund = e.RefundResult;
System.Console.WriteLine(e.Message);
foreach (APIError error in e.Errors)
{
System.Console.WriteLine("Fehler {0}: {1}, {2}", error.Code, error.Id, error.Message);
}
}
RefundsResponse refunds = await merchantClient .Payments .GetRefunds(paymentId);
if (IsNotSuccessful(refunds, refundId))
{
HandleError(refunds);
}

HTTP-Ausnahmen

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

Jedes der folgenden Code-Beispiele können Sie mit dieser CreatePayment-Standardanfrage kombinieren:


CreatePaymentResponse createPaymentResponse;

// Felder für eine minimale CreatePaymentResponse initialisieren
CreatePaymentRequest body = new CreatePaymentRequest()
{
    Order = new Order
    {
        AmountOfMoney = new AmountOfMoney
            {
                Amount = 100,
                CurrencyCode = "EUR"
            }
    },
    CardPaymentMethodSpecificInput = new CardPaymentMethodSpecificInput
    {
        Card = new Card
        {
            CardholderName = "Wile E. Coyote",
            CardNumber = "4111111111111111",
            Cvv = "123",
            ExpiryDate = "1236"
        }
    }
};

// IMerchantClient für eine asynchrone Anfrage an Ihre PSPID verwenden 
try
{
createPaymentResponse = await merchantClient
    .Payments
    .CreatePayment(body);
}
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)

{
System.Console.WriteLine("Fehler bei Input-Validierung:");
foreach (APIError error in e.Errors)
{
if (error.PropertyName == null)
{
System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
}
else
{ System.Console.WriteLine("- {0}: {1}: {2}", error.PropertyName, error.Code,
error.Message);
}
}
}
AuthorizationException /
403
catch (AuthorizationException e)

{
System.Console.WriteLine("Autorisierungsfehler:");
foreach (APIError error ine.Errors)
{
System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
}
}
IdempotenceException /
409
catch (IdempotenceException e)
{
    System.Console.WriteLine("Autorisierungsfehler:");
    foreach (APIError error in e.Errors)
    {
        System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
    }
}
ReferenceException /
404/409/410
catch (ReferenceException e)
{
    System.Console.WriteLine("Falsche Objektreferenz:");
    foreach (APIError error ine.Errors)
    {
        System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
    }
}
DirectException /
500/502/503
catch (DirectException e)
{
    System.Console.WriteLine("Fehler bei Direct oder einem nachgeordneten Partner/Acquirer:");
    foreach (APIError error ine.Errors)
    {
        System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
    }
}
ApiException /
Sonstige Codes
catch (ApiException e)
{
    System.Console.WriteLine("Plaftformfehler: ");
    foreach (APIError error ine.Errors)
    {
        System.Console.WriteLine("- {0}: {1}", error.Code, error.Message);
    }
}
CommunicationException /
300er-Codes ohne Body oder Nicht-JSON-Antwort
catch (CommunicationException e)
{
    System.Console.WriteLine("Kommunikationsfehler: {0}", e.InnerException.ToString());
}

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
CreatePaymentResult ist in der Antwort vorhanden

Payment Rejected

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

DeclinedPaymentException

Verschiedenes
PayoutResult ist in der Antwort vorhanden

Payout Rejected

Ihre Anfrage wurde entweder von der Direct-Plattform oder von einem unserer nachgeordneten Partner/Acquirer abgelehnt

DeclinedPayoutException

Verschiedenes
RefundsResponse ist in der Antwort vorhanden

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, was nicht erlaubt ist oder wozu Sie nicht befugt sind

AuthorizationException
404

Not Found

Das Objekt, auf das Sie einen Zugriff versucht haben, konnte auf dem Server nicht gefunden werden

ReferenceException
409

Conflict
Ihre idempotente Anfrage hat zu einem Konflikt geführt, weil 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 gelöscht.

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 - sie helfen Ihnen beim Entwickeln der perfekten Lösung.

Verfügbare Zahlungsarten abrufen

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


// Anfrage zum Abruf aller aktiven Zahlungsmethoden in Ihrer PSPID erstellen
var queryParams = new GetPaymentProductsParams
{
    CountryCode = "BE",
    CurrencyCode = "EUR"
};

// Anfrage senden und Antwort abrufen
GetPaymentProductsResponse response = await client
    .WithNewMerchant("IhrePSPID")
    .Products
    .GetPaymentProducts(queryParams);

Idempotente Anfragen senden

Eines der wichtigsten Merkmale der REST API ist die 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 mit seiner Eigenschaft IdempotenceKey für eine CreatePayment Anfrage. Das SDK sendet einen -GCS-Idempotence-Key-Header mit dem Idempotenz-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 Idempotenz-Schlüssel senden, enthält die Antwort einen X-GCS-Idempotence-Request-Timestamp-Header. Das SDK setzt die Eigenschaft IdempotenceRequestTimestamp des Arguments CallContext
  • 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 Idempotenz-Schlüssel und dem Zeitstempel der idempotenten Anfrage

String idempotenceKey = "IhrSchlüsselFürDieZahlung"
CallContext context = new CallContext().WithIdempotenceKey(idempotenceKey);
try
{
    CreatePaymentResponse response = await client
        .WithNewMerchant("IhrePSPID")
        .Payments
        .CreatePayment(body);
}
catch (IdempotenceException e)
{
    // Eine Anfrage mit demselben idempotenceKey läuft noch, nach einer kurzen Pause noch einmal versuchen
    // e.IdempotenceRequestTimestamp enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
}
finally
{
    long? idempotenceRequestTimestamp = context.IdempotenceRequestTimestamp;
    // idempotenceRequestTimestamp enthält den Wert des
    // Headers X-GCS-Idempotence-Request-Timestamp
    // wenn idempotenceRequestTimestamp nicht null ist, war es 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 Ausnahmen. Diese Protokolle können hilfreich bei der Fehlersuche oder der Nachverfolgung einzelner Schritte im Zahlungsablauf sein.
Das SDK bietet zwei Implementierungen der Protokollierungsfunktion:

  • System.Console (SystemConsoleCommunicatorLogger)
  • NLog (NLogCommunicatorLogger)

Zum Aktivieren bzw. Deaktivieren der Protokollierung können Sie die Methoden EnableLogging bzw. DisableLogging für eine IClient-Instanz aufrufen:


client = Factory.CreateClient("IhrAPISchlüssel", "IhrAPIGeheimis", apiEndpoint, "IhrFimenname");
CommunicatorLogger logger = new NLogLogger(Logger.GetCurrentClassLogger(), Level.Info); 
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. IClient-Instanzen, die wie im Kapitel SDK initialisieren beschrieben erzeugt wurden, haben ihren eigenen Verbindungspool. Mit demselben ICommunicator-Objekt erzeugte IClient-Instanzen teilen sich einen Verbindungspool.

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

  1. Einen gemeinsamen ICommunicator erzeugen. Dafür können Sie die Klasse Factory verwenden
  2. IClient-Instanzen mit diesem ICommunicator erzeugen

ICommunicator communicator = Factory.CreateCommunicator("apiKeyId", "apiKey", apiEndpoint, "IhrFimenname"); 

// Einen oder mehrere Client(s) mit dem gemeinsamen Kommunikator erzeugen 
IClient client = Factory.CreateClient(communicator); 

Wenn Sie den ICommunicator nicht mehr benötigen, empfehlen wir, ihn zu schließen. Beachten Sie Folgendes:

  • ICommunicator und IClient implementieren System.IDisposable, Sie können sie in using-Anweisungen verwenden
  • Verwenden Sie die Methode CloseExpiredConnections für die ICommunicator-Instanz oder die IClient-Instanzen zum Schließen abgelaufener HTTP-Verbindungen
Wenn Sie eine IClient-Instanz schließen/löschen, die denselben ICommunicator nutzt oder in einer using-Anweisung verwendet, wird auch die ICommunicator-Instanz gelöscht/geschlossen. Das Löschen/Schließen von ICommunicator löscht/schließt alle IClient-Instanzen, die ihn nutzen

Kommunikation anpassen

IClient-Instanzen kommunizieren über eine ICommunicator-Instanz mit unserer Plattform. ICommunicator-Implementierungen wandeln ein Anfrageobjekt in eine HTTP-Anfrage um, und eine HTTP-Antwort in ein Antwortobjekt.

Das SDK bietet eine Standardimplementierung von ICommunicator, aber Sie können auch eine eigene Implementierung dieser Schnittstelle für Ihren Bedarf verwenden:


ICommunicator communicator = new YourCommunicator(); 
IClient client = Factory.CreateClient(communicator); 

Eine eigene Implementierung ist in den meisten Fällen nicht erforderlich. Die Funktionen des Standard-Communicator sind auf den Klassen Authenticator, Connection,  Marshaller and  MetaDataProvider aufgebaut. Die Implementierung dieser Klassen kann einfach für Ihre Bedürfnisse erweitert oder ersetzt werden. Marshaller wird zum Marshalling und Unmarshalling von Anfrage- und Antwortobjekten in und aus JSON verwendet und sollte nicht verändert werden. Für die Kommunikation mit unserer Plattform werden außerdem folgende Module benötigt:

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

Zur Vereinfachung für Sie stellen wir einen ICommunicator-Builder bereit, mit dem Sie eines oder mehrere dieser Module leicht ersetzen können. Um zum Beispiel eine Instanz von IClient zu erzeugen, der Ihre eigene Implementierung von Connection verwendet, können Sie das folgende Stück Code verwenden:


Connection connection = new YourConnection(); 
ICommunicator communicator = Factory.createCommunicator(dictionary, "apiKeyId", "apiKey") 
    .WithConnection(connection) 
    .Build(); 
Client client = Factory.CreateClient(communicator); 

Webhooks

Der für Webhooks zuständige Teil des SDK wird als Webhooks-Helper bezeichnet. Es übernimmt in transparenter Weise sowohl die Validierung von Signaturen anhand der vom Webhook-System gesendeten Event-Bodies (einschließlich Ermittlung des geheimen Schlüssels für die Schlüssel-IDs - nicht zu verwechseln mit dem API-Schlüssel und dem API-Geheimnis) als auch das Unmarshalling dieser Bodies in Objekte. So können Sie sich auf das Wesentliche konzentrieren und brauchen nicht alle zusätzlichen Informationen selbst durchzugehen und die gewünschten Informationen zu extrahieren. Mehr über Webhooks erfahren Sie in Sie unserer speziellen Anleitung zu diesem Thema. 

Geheime Schlüssel konfigurieren

Konfigurieren Sie den „WebhooksKey“ / den „WebhooksKeySecret“ und Ihre Server-Webhooks-Endpunkte im Merchant Portal:


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

Verwenden Sie InMemorySecretKeyStore.Instance.StoreSecretKey(keyId, secretKey) zum Speichern eines geheimen Schlüssels für eine Schlüssel-ID.

Schlüssel können mit folgenden Funktionen hinzugefügt oder gelöscht werden:

  • InMemorySecretKeyStore.Instance.GetSecretKey(keyId)
  • InMemorySecretKeyStore.Instance.RemoveSecretKey(keyId) zum Löschen des geheimen Schlüssels für eine Schlüssel-ID
  • InMemorySecretKeyStore.Instance.Clear() zum Löschen aller gespeicherten geheimen Schlüssel

Wenn Sie eine erweiterte Speicherung brauchen, z. B. in einer Datenbank oder einem Dateisystem, empfehlen wir, eine eigene Implementierung zu schreiben. 

Webhooks-Helper initialisieren

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


WebhooksHelper helper = Webhooks.CreateHelper(InMemorySecretKeyStore.Instance);

Webhooks-Helper verwenden

Zum Verarbeiten der von einem Webhook empfangenen Events rufen Sie zunächst die unmarshal-Methode des WebhooksHelper-Objekts auf. Die Methode nimmt die folgenden Argumente entgegen: 

  • den Body als Zeichenfolge. Das muss der rohe Body sein, wie er vom Webhook-System empfangen wird

    String bodyOfRequest = "JSON_Body_Of_The_Request";
  • Eine Liste der vom Webhook-System empfangenen Anfrage-Header. Nachfolgend finden Sie ein Beispiel für das Erzeugen einer Liste mit Anfrage-Headern. Sie muss zwei Header enthalten (keyId und signature):
    
    

    // Retrieve the headers from the Webhook message, depends on your implementation. var webhookHeaders = request.Headers; // Transform the received headers var requestHeaders = new List<RequestHeader>(); foreach (var webhookHeader in webhookHeaders) { requestHeaders.Add(new RequestHeader(webhookHeader.Name, webhookHeader.Value)); }

  • Jetzt können Sie einen Webhook-Helper für zum Unmarshalling eingehender Events nutzen. Das gestattet es Ihnen, Daten in Ihrer Anwendung zu verarbeiten:

    try
    {
    WebhooksEvent event = helper.Unmarshal(bodyOfRequest, requestHeaders);
    }
    catch (SignatureValidationException ex)
    {
    // Your code to handle errors
    
    }

Was this page helpful?

Do you have any comments?

Thank you for your response.