Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above

1. Introduction

To create payments, you need to link your server to our platform via one of our integration modes.
Our Node.js SDK library is the ideal solution to connect to our platform if you prefer to do so with your own stand-alone system using Node.js language.

Choosing the Node.js SDK, you can:

To take full advantage of this SDK, make sure you meet these requirements:

  • Node.js 8 or higher

Install the latest version of the Node.js SDK using NPM package manager by running:

npm i direct-sdk

Find more details on GitHub. Also, check out all available SDK objects and properties in our Full API Reference. Once you are all set, read the next chapters on how to prepare and use the SDK.

This guide provides a general overview on the SDK’s functionalities. To see how they precisely work for the different integration modes, see the dedicated guides explaining every step with full code samples:

Target most up-to-date API base URL

We encourage you to always target the most up-to-date API base URL when sending requests to our platform. Have a look at our dedicated guides for a full overview:

To allow you a smooth transition, previous API base URLs remain available until further notice.

2. Initialise SDK

To connect your system to our platform by using the SDK, you need to initialise it at first.

Initialising the SDK requires you to

  • Create test/live account
  • Create an API Key and API Secret for the PSPID you wish to use for transaction processing
  • Check the API endpoints needed for both test and live environment

    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 API endpoint for the test/live environment is

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


    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

  • Initialise an instance of directSdk using the API Key / API Secret to set up the connection to our test/live platform
  • Download our SDK code following the way presented in chapter 1

After initialisation, you can start processing transactions via your PSPID. Learn how this works in the dedicated chapter.

Have a look at code samples of two connection methods covering the steps mentioned above:


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

directSdk.init({
integrator: '[your-company-name]', // used for identification in logs
host: '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]'
});

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

The following table provides an overview of the arguments accepted by the individual instances:

Properties
  • string merchantId: Your PSPID in either our test environment/live environment. Make sure to use the correct API Key / API Secret together with the conjoining PSPID for your transactions request
  • string apiKey: The API Key you have defined in your PSPID to which you will send the transactions to
  • string apiSecret: The API Secret you have defined in your PSPID to which you will send the transactions to

    Check out our dedicated guide to learn all about API Key / API Secret

  • string apiEndpoint: It contains a link to either our test or live environment where your transaction requests are sent to

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

  • string integrator: Your (company) name or any unique identifier. We can use the value for debugging and tracking request you have sent to our platform. Therefore, we strongly suggest sending a value we can identify your requests easily in our logs
You can re-use a Client instance for different calls. You can use

  • The MerchantClient class object initialised in the example for all calls for that PSPID
  • The Client instance to create MerchantClients for different (or the same) PSPIDs


After you have initialised the SDK, you can send requests to our platform via your PSPID. Learn in the next chapter how to do this.

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

3. Use SDK

After the successful initialisation of the directSdk instance, you gain full access to our RESTful API. It enables you to:

  • Send requests for new transactions for any of our server integration modes
  • Get your transactions’ current status
  • Perform maintenance requests (i.e., captures, refunds) on existing transactions
  • Make sure that the payment method you would like to use is active in your test/live account via Configuration > Payment Methods > Selected payment methods > Column "Status": 
  • To change the activation status of a payment method, click on the edit symbol (the pen in the green square). Go to tab PM activation and select "Yes" for "Activation". Confirm by clicking the "SUBMIT" button

Check out our test cases in GitHub, including full code samples, and our Full API Reference to learn what is possible.

Below you may find some of the most common actions you can perform:

Create new transactions

To create a new transaction, you can use a directSdk  instance for any of our integration modes to create a new transaction. It can be done through: 

  • Routing the request to your PSPID on our platform (for directSdk)
  • Creating a request for the respective integration mode

The SDK instance only keeps track of the data used to initialise it. It does not track neither active sessions nor previous requests. Your system is responsible for managing Direct sessions and payments

Sessions and payments do not impact other sessions and payments

Below you can find code samples related to particular integration modes:

Hosted Checkout Page

To use this integration mode, you need to create a CreateHostedCheckoutRequest call. It must contain at least an Order object.

You can specify an optional returnUrl, which will be used to redirect your customer back to your website

/* 
 *…. 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",
},
},
{}
);

This call returns a CreateHostedCheckoutResponse response. Store the hostedCheckoutId and RETURNMAC it contains, as well as any other information relevant for you. You will need these for steps described in the following chapters.

This response also contains a partialRedirectURL.

You have to concatenate the base URL "https://payment." with partialRedirectURL according to the formula

https://payment. + partialRedirectURL

and perform redirection of your customer to this URL. Once the customer visits the Hosted Checkout Page, the payment process continues there.

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. 

Hosted Tokenization Page

To use this integration method, you need to


// Initialisation

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

From sdkResponse retrieve hostedTokenizationId and partialRedirectUrl.

You will need these for steps described in the following chapters. The payment continues on the check-out page according to Hosted Tokenization Page. Then, create the actual payment with the token: 


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

You can also send the tokenID instead of the hostedTokenizationId in your CreatePayment request. Learn more about using either option in the dedicated chapters of our Hosted Tokenization Page guide:

Server-to-server

A minimum paymentResponse requires you to set at least an Order object and a payment method:


// 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",
},
},
order: {
amountOfMoney: {
currencyCode: "EUR",
amount: 2980,
},
},
},
{}
);

We have dedicated guides for each of the aforementioned integration modes:

The documents contain all crucial details you need to profit from the integration modes’ full potential, including full transaction flows, code samples and other useful features

Get transaction status

Our RESTful API allows you to request a transaction’s status anytime by one of our GET calls:

A GetPayment request looks like this: 


const merchantId = "PSPID";
const sdkResponse = await directSdk.payments.getPayment(merchantId, 'PAYMENT_ID',{});
Properties
string PAYMENT_ID: The 10-digit unique reference of your transaction on our platform. This reference can be retrieved from the directSdk.payments.createPayment()
 or directSdk.hostedCheckout.createHostedCheckout() created in the previous section.

For more information about statuses visit the status documentation page.

Perform maintenance operation

To perform follow-up actions on existing transactions (i.e. captures or refunds), use our CapturePayment or RefundPayment API call respectively:

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,
},
},
{}
);
Properties
string PAYMENT_ID: The 10-digit unique reference of your transaction on our platform. This reference can be retrieved from the directSdk.payments.createPayment()  or directSdk.hostedCheckout.createHostedCheckout() created in the previous section.

4. Handle exceptions

If a transaction is rejected, our platform provides detailed information with an Exception instance. The affiliated HTTP status code also help you troubleshoot the error.

You can encounter two types of exceptions: transaction exceptions and HTTP exceptions.

Transaction exceptions

This kind of exception refers to transaction requests that are technically correct but were rejected by your customer’s issuer or your acquirer. If the transaction is returned in the exception, it means that it was created in our systems but not successfully processed. 

The following code samples use implicit methods provided as an example. You are expected to provide your own implementation for these or replace them with similar logic

Exception type /
HTTP status code
Code Sample
Rejected transactions / 
Various(see PaymentResponse object)

// 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);
}
Rejected Refund /
Various(see PaymentResponse object)


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

This kind of exception refers to various problems caused by technical errors in the API call or payment request.

You can combine any of the following code snippets with this standard CreatePayment request:

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

Exception type / 
HTTP status code
Code Sample
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 /
Any other codes
if (response.errors.length > -1) {
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}
CommunicationException /
300 codes without a body or non-JSON response
if (response.status.match(/3[0-9]{2}\b/)) {
console.log("Communication error:");
response.errors.forEach((error) => {
console.log(error.code, error.message);
});
}}

HTTP status codes 

All our exceptions are linked to one or more HTTP status codes, indicating the root cause for many possible errors.

Status code Description
200

Successful
Our platform processed your request correctly

201

Created
Our platform processed your request correctly and created a new resource. We return the URI of this resource in the Location header of the response

204

No content
Our platform processed your request correctly

Various
CreatePaymentResult key is in the response

Payment Rejected
Either our platform or one of our downstream partners/acquirers rejected your request

Various
PayoutResult is present in the response

Your request was rejected either by the Direct platform or one of our downstream partners/acquirers

Various
RefundResult key is in the response

Refund Rejected
Either our platform or one of our downstream partners/acquirers rejected your request

400

Bad Request
Your request contains errors, thus our platform cannot process it

403

Not Authorised
You are trying to do something that is not allowed or that you are not authorised to do

404

Not Found
The object you were trying to access could not be found on the server

409

Conflict
Your idempotent request resulted in a conflict because of either: 

  • The first request has not finished yet
  • Your request resulted in a conflict. Either you submitted a duplicate request, or you are trying to create something with a duplicate key
410

Gone
The object that you are trying to reach has been removed.

500

Internal Server Error
An error occurred on our platform

502 Bad Gateway
Our platform was unable to process a message from a downstream partner/acquirer
503 Service Unavailable
The service that you are trying to reach is temporarily unavailable. Please try again later
Other Unexpected error
An unexpected error has occurred

5. Use additional features

The SDK has a lot more to offer. Have a look at the following features, as they will help you build the perfect solution.

Get available payment methods

Before you initiate the actual payment process, you send a GetPaymentProducts request to our platform. The response contains a list of available payment methods in your PSPID. Depending on your customers’ preferences, you can offer a selection on our Hosted Checkout Page or on your own webshop environment using subsequent CreatePayment requests.


// Initialisation
const merchantId = "PSPID" const paymentProducts = await directSdk.products.getPaymentProducts(merchantId, { countryCode: 'NL', currencyCode: 'EUR', });

Send idempotent requests

One of the main REST API features is its ability to detect and prevent sending requests (i.e. payment requests) accidentally twice. The SDK makes it very easy for you to ensure that you send only unique – idempotent – requests to our platform.

Use the additional argument paymentContext and set its property named idempotence  to a CreatePayment request. The SDK will send an X-GCS-Idempotence-Key header with the idempotence key as its value.

If you send requests this way to our platform, we will check the following

  • If you send subsequent request with the same idempotence key, the response contains an X-GCS-Idempotence-Request-Timestamp header. The SDK will set the idempotenceRequestTimestamp property of the CallContext argument
  • If the first request is not finished yet, the RESTful Server API returns a 409 status code. Then the SDK throws an IdempotenceException with the original idempotence key and the idempotence request timestamp

// Initialisation

const merchantId = "PSPID";

directSdk.payments.createPayment(
merchantId,
{
cardPaymentMethodSpecificInput: {
card: {
cvv: "123",
cardNumber: "4567350000427977",
expiryDate: "1220",
cardholderName: "Wile E. Coyote",
},
},
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()
);
}
}
);

If an idempotence key is sent for a call that does not support idempotence, the RESTful Server API will ignore the key and treat the request as a first request.


Use logging

The SDK supports logging of requests, responses, and exceptions of the API communication. These can be helpful for troubleshooting or tracing individual steps in the payment flow.

To use this logging feature, you should implement the CommunicatorLogger interface.

The SDK offers two implementations of the logging feature:

  • System.out (SysOutCommunicatorLogger)
  • java.util.logging.Logger (JdkCOmmunicatorLogger)
Make sure to use the following classes:
  • ResourceLogger

To use this feature, provide an implementation of the Logger interface . You can enable/disable the logging by setting the enableLogging property and providing the logger as an argument 'logger'.

To use this feature, provide an implementation of the Logger interface . You can enable/disable the logging by setting the enableLogging property on a directSdk object and providing the logger as an argument logger.

The SDK obfuscates sensitive data in the logger

Webhooks

The part of the SDK that handles the webhooks support is called the webhooks helper. It transparently handles both validation of signatures against the event bodies sent by the webhooks system (including finding the secret key for key IDs - not to be confused with the API Key and API Secret), and unmarshalling of these bodies to objects. This allows you to focus on the essentials, without going through all the additional information and extracting the desired ones by yourself. To learn more about webhooks, read our dedicated guide. 

Provide secret keys

Configure the "WebhooksKey" / "WebhooksKeySecret" and your server webhooks endpoints in the Back Office:


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

Secret keys are provided using a function that takes two arguments:

  • The key ID to return the secret key for
  • A callback function that either takes an error as its first argument, or the secret key for the given key ID as its second argument (in which case the first argument must be null)

The SDK provides one implementation for this function: webhooks.inMemorySecretKeyStore.getSecretKey. This will retrieve secret keys from an in-memory key store.

You can add or remove keys using the following functions:

  • webhooks.inMemorySecretKeyStore.storeSecretKey(keyId, secretKey) to store a secret key for a key ID
  • webhooks.inMemorySecretKeyStore.removeSecretKey(keyId) to remove the stored secret key for a key ID
  • webhooks.inMemorySecretKeyStore.clear() to remove all stored secret keys

If you require more advanced storage, e.g. for a database or file system, we recommend writing your own implementation.

Initialise webhooks helper

Include and initialise the webhooks helper as follows:

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

Use webhook helper

From an entry point that you have created on your own, call the unmarshal method of the webhooks helper. It takes the following arguments:

  • The body as a string or Buffer. This should be the raw body as received from the webhooks system
  • An object containing the request headers as received from the webhooks system. The keys should be the header names

// Initialisation
webhooks.unmarshal(body, requestHeaders, (error, event) => {
if (error) {
// something went wrong in validating the signature or unmarshalling the event
} else {
// process the event
}
});