worldline Direct
Sign up

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 Node.js 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:

  • Node.js 8 oder höher

IInstallieren Sie die neueste Version des Node.js-SDK mit dem NPM package manager, indem Sie Folgendes ausführen:

npm i onlinepayments-sdk-nodejs

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:

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 Anbinden Ihres Systems mit Hilfe des SDK an unsere Plattform müssen Sie es zunächst initialisieren.

Die Initialisierung umfasst:

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:


const directSdk = require('direct-sdk-nodejs');

directSdk.init({
integrator: '[your-company-name]', // used for identification in logs
host: 'payment.preprod.direct.worldline-solutions.com/', // Note: Use the endpoint without the /v2/ part here. This endpoint is pointing to the TEST server
scheme: 'https', // default
port: 443, // default
enableLogging: true, // defaults to false
logger: logger, // if undefined console.log will be used
apiKeyId: '[your-api-key-id]',
secretApiKey: '[your-secret-api-key]'
});

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

Properties
  • 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
  • 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
Client-Instanzen sind für verschiedene Aufrufe wiederverwendbar. Sie können Folgendes verwenden: 

  • Das Objekt der Klasse MerchantClient, das in dem Beispiel für alle Aufrufe für diese PSPID initialisiert wird
  • Die Client-Instanz zum Erstellen von MerchantClients für verschiedene (oder dieselben) PSPIDs


Nach der SDK-Initialisierung können Sie über Ihre PSPID Anfragen an unsere Plattform senden. Im nächsten Kapitel erfahren Sie, wie Sie dies tun 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 directSdk-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
The newest version of our SDK also returns the full path in redirectURL, allowing you to skip concatenate the base URL "https://payment." with partialRedirectURL. Learn more more in our  Hosted Checkout Page  guide. 

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

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

  • Weiterleitung der Anfrage an Ihre PSPID auf unserer Plattform (für directSdk)
  • 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

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

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:


const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.getPayment(merchantId, 'PAYMENT_ID',{});
Eigenschaften
string PAYMENT_ID: Die eindeutige Referenz für Ihre Transaktion auf unserer Plattform. Diese Referenz ist von directSdk.payments.createPayment()
oder directSdk.hostedCheckout.createHostedCheckout() 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


/* 
 *…. Initialisation....
 */
const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.capturePayment(
merchantId,
"PAYMENT_ID",
{
amount: 2980,
isFinal: true,
},
{}
);

RefundPayment

/*  
 *…. Initialisation.... 
 */ 
 
const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.refundPayment(
merchantId,
"PAYMENT_ID",
{
amountOfMoney: {
currencyCode: "EUR",
amount: 1,
},
},
{}
);
Eigenschaften
string PAYMENT_ID: Die eindeutige Referenz für Ihre Transaktion auf unserer Plattform. Diese Referenz ist von directSdk.payments.createPayment() oder directSdk.hostedCheckout.createHostedCheckout() abrufbar, die im vorherigen Abschnitt erstellt wurde.

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

const merchantId = "PSPID";
const sdkResponse= await directSdk.hostedCheckout.createHostedCheckout(
merchantId,
{
order: {
amountOfMoney: {
currencyCode: "USD",
amount: 2345,
},
customer: {
merchantCustomerId: "1234",
billingAddress: {
countryCode: "US",
},
},
},
hostedCheckoutSpecificInput: {
variant: "testVariant",
locale: "en_GB",
},
},
{}
);
Response 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.

Hosted Tokenization Page

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


// Initialisation

const merchantId = "PSPID";
const sdkResponse = await directSdk.hostedTokenization.createHostedTokenization(
merchantId,
{
askConsumerConsent: true,
locale: "en_GB",
variant: 'YOUR_TEMPLATE.html',
}, 
{}
);

Von sdkResponse müssen SieehostedTokenizationId 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:

// Initialisation

const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
token: 'TOKEN_FROM_HOSTED_TOKENIZATION_RESPONSE',
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
  {}
);

Server-to-server

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


// The example object of the AmountOfMoney
const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977", // // Find more test data here
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3,
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
{}
);

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

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)

// Initialisation
const merchantId = "PSPID";
let paymentId = null;
try {
paymentId = directSdk.payments.createPayment(merchantId, {}, {});
} catch (error) {
console.error(error);
return;
}

const payment = await directSdk.payments.getPayment(merchantId, paymentId, {});

if (isNotSuccessful(payment)) {
handleError(payment);
}
Abgelehnte Gutschriften /
Verschiedenes (siehe PaymentResponse-Objekt)

// Initialisation

const merchantId = "PSPID";
const payId = "PAY_ID";
let refundId = null;

try {
refundId = await sdkInstance.payments.refundPayment(
merchantId,
payId,
{
amountOfMoney: {
currencyCode: "EUR",
amount: 1,
},
},
{}
);
} catch (error) {
console.error(error);
return;
}

const refunds = await directSdk.payments.getRefunds(merchantId, payId, {});

if (isNotSuccessful(refunds, refundId)) {
handleError(refunds);
}

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


const merchantId = "PSPID";
const sdkResponse = null;
try {
sdkResponse = await directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3,
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
{}
);
} catch (error) {
// something went wrong, lets log it...
console.error(error);
return;
}
if (sdkResponse.errors.length > -1) {
// we've got a specific error
sdkResponse.forEach((error) => {
// your error handling logic
console.error(error);
});
}

Ausnahmetyp /
HTTP-Statuscode
Codebeispiel
ValidationException /
400
if (response.status === 400) {
console.log("Input validation error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}
AuthorizationException /
403
if (response.status === 403) {
console.log("Authorization error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}
IdempotenceException /
409
if (response.status === 409) {
console.log("Authorization error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}
ReferenceException /
404/409/410
if (
response.status === 404 ||
response.status === 409 ||
response.status === 410
) {
console.log("Incorrect object reference:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}
DirectException /
500/502/503
if (
response.status === 500 ||
response.status === 502 ||
response.status === 503
) {
console.log(" Error occurred at Direct or a downstream partner/acquirer:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}
ApiException /
Alle anderen Statuscodes
if (response.errors.length > -1) {
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}
CommunicationException /
300er-Codes ohne Anfrageinhalt oder Antwort nicht im JSON-Format
if (response.status.match(/3[0-9]{2}\b/)) {
console.log("Communication error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

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

ValidationExeption
403

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

AuthorizationExeption
404

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

ReferenceExeption
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

IdempotenceExeption
ReferenceExeption

410

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

ReferenceExeption
500

Internal Server Error
Auf unserer Plattform ist ein Fehler aufgetreten

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

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 können 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
const merchantId = "PSPID" const paymentProducts = await directSdk.products.getPaymentProducts(merchantId, { countryCode: 'NL', currencyCode: 'EUR', });

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

const merchantId = "PSPID";

directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
paymentProductId: 3, }, order: { amountOfMoney: { currencyCode: "EUR", amount: 2980, }, }, }, { idemPotence: { key: "YourKeyForThePayment" } }, (error, sdkResponse) => { if (directSdk.context.getIdempotenceRequestTimestamp()) { // this call is made with idempotence and is still being handled console.log( "idempotence timestamp", directSdk.context.getIdempotenceRequestTimestamp() ); } } );

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

Um diese Funktion nutzen zu können, müssen Sie eine Implementierung der Logger-Schnittstelle bereitstellen. Sie können die Protokollierung aktivieren/deaktivieren, indem Sie die enableLogging-Eigenschaft eines directSdk-Objekts modifizeren und den Logger als logger Argument angeben

Das SDK verbirgt sensible Daten im Logger

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. 

Bereitstellung von Secret Keys

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


keyId = '[WebhooksKey"]',
secretKey = '[WebhooksKeySecret]'

Secret keys werden mit einer Funktion bereitgestellt, die zwei Argumente benötigt:

  • Die Key ID zur Rückgabe des Secret Key
  • Eine Callback-Funktion, die entweder einen Fehler als erstes Argument annimmt oder den Secret Keys für die vorgegebene key ID als zweites Argument annimmt (in diesem Fall muss das erste Argument nullsein)

Das SDK bietet eine Implementierung für diese Funktion: webhooks.inMemorySecretKeyStore.getSecretKey. Damit werden Secret Keys aus einem speicherinternen Schlüsselspeicher abgerufen..

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

  • webhooks.inMemorySecretKeyStore.storeSecretKey(keyId, secretKey) zum Speichern eines Secret Key für eine Key ID
  • webhooks.inMemorySecretKeyStore.removeSecretKey(keyId) zum Entfernen des gespeicherten Secret Key für eine Key ID
  • webhooks.inMemorySecretKeyStore.clear() zum Entfernen aller gespeicherten Secret Keys

Wenn Sie eine erweiterte Speicherung benötigen, z. B. für eine Datenbank oder ein Dateisystem, empfehlen wir Ihnen das Schreiben einer eigenen Implementierung.

Webhooks Helper initialisieren

Binden Sie den Webhooks Helper wie folgt ein und initialisieren Sie ihn:

// Initialisation
const webhooks = require("direct-sdk-nodejs").webhooks;
// replace webhooks.inMemorySecretKeyStore.getSecretKey with your own function if needed
webhooks.init({
getSecretKey: webhooks.inMemorySecretKeyStore.getSecretKey,
});

Webhooks Helper verwenden

Rufen Sie von einem selbst erstellten Einstiegspunkt aus die unmarshal-Methode von webhooks Helper auf. Er benötigt die folgenden Argumente:

  • Den Text als string oder Buffer. Dies sollte der Rohtext sein, wie er vom Webhooks-System empfangen wurde
  • Ein Objekt, das die Header der Anfrage enthält, wie sie vom Webhooks-System empfangen wurde. Die Keys müssen die Header-Namen sein
// Initialisation
webhooks.unmarshal(body, requestHeaders, (error, event) => {
    if (error) {
        // something went wrong in validating the signature or unmarshalling the event
    } else {
        // process the event
    }
});

Was this page helpful?

Do you have any comments?

Thank you for your response.