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

• 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.

Aktuellste API Basis-URL nutzen

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
• 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 directSdk 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:

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:

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.

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

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

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:

const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.getPayment(merchantId, 'PAYMENT_ID',{});

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,
},
},
{}
);

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

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

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

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

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

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.

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

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

if (response.status === 400) {
console.log("Input validation error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}

if (response.status === 403) {
console.log("Authorization error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}

if (response.status === 409) {
console.log("Authorization error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

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

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

if (response.errors.length > -1) {
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

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.

IdempotenceExeption
ReferenceExeption

ReferenceExeption

DirectExeption

DirectExeption

DirectExeption

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
• Senden idempotenter Anfragen
• Protokollierung verwenden
• Webhooks

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

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)

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

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