Node.js SDK

Introduction

The Node.js SDK helps you to communicate with the Server API. More specifically, it offers a fluent Node.js API that provides access to all the functionality of the RESTful Server API. Below, we discuss the following topics in detail.

• Initialization of the SDK
• Payments
• File Service support
• Idempotent requests
• Errors
• Logging
• Advanced use: Customization of the communication
• Webhooks

The source code of the SDK and an example app are available on Github . There you can find installation instructions.

The API documentation of the latest version of the SDK is available here . For a specific major version, replace latest with <major>.x. Note that this is only available for versions 5.x and later. For version 4.x use this URL instead.

Initialization of the Node.js SDK

All JavaScript code snippets presented in the API reference assume you have initialized the Node.js SDK before using them in your Development Environment. This section details the initialization of the Node.js SDK.

Initializing is simple, and requires only one key task: use our connect-sdk-nodejs package to create an instance of Client, which contains the actual methods to communicate with the Server API.

The Client needs the following input

• The host, scheme and port to which you connect. See API endpoints for the possible hosts.
• The secretApiKey and apiKeyId. The secretApiKey is a key that is used to authenticate your API requests, and apiKeyId identifies that key (as you can have multiple active keys). Both of these can be obtained from the Account Setup tab of the Configuration Center, and are available only if you are administrator.
• The name of the integrator, e.g. your company name.
• Optional logging properties.

import * as connectSdk from "connect-sdk-nodejs";

const client = connectSdk.init({
  host: "[hostname.of.the.api]",
  scheme: "https",
  port: 443,
  enableLogging: true, // defaults to false
  logger: logger, // if undefined console.log will be used
  apiKeyId: "[your-api-key-id]",
  secretApiKey: "[your-secret-api-key]",
  integrator: "[your-company-name]"
});

If a proxy should be used, the input should additionally contain a proxy property:

const client = connectSdk.init({
  host: "[hostname.of.the.api]",
  scheme: "https",
  port: 443,
  enableLogging: true, // defaults to false
  logger: logger, // if undefined console.log will be used
  apiKeyId: "[your-api-key-id]",
  secretApiKey: "[your-secret-api-key]",
  integrator: "[your-company-name]",
  proxy: {
    host: "[hostname.of.the.proxy]",
    scheme: "http",
    port: 3128,
    credentials: "[username.for.the.proxy]:[password.for.the.proxy]"
  }
});

Only the nested host property is required; the scheme and port properties default to http and 3128 respectively, and the credentials property can be omitted if no proxy authentication is needed.

Payments

As a merchant, your core interaction with Worldline typically starts when your customer clicks the checkout button in your application. The payment process usually has the following steps:

1. Payment Product selection
2. Setting of available information needed for selected payment product (e.g. amount of the order)
3. Collection of missing customer information needed for selected payment product (e.g. creditcard number)
4. Submitting the payment request to the Worldline platform
5. Handling the response to the payment request (e.g. payment unsuccessful)

The Worldline platform offers three ways of handling this payment process:

• Use a hosted payment through the MyCheckout hosted payment pages.
  In this case, you redirect the customer to our hosted payment pages. For you as a merchant, this is the easiest option as the Worldline platform can handle payment product selection and is responsible for the collection of sensitive data like a creditcard number. Through our Configuration Center, you still have a lot of control over the look and feel of the checkout.
• Use a Client SDK to build a payment flow for a native app or a JavaScript application.
  In this case, your server requests the creation of a client session. This returns a session id with which your client application can communicate with the Worldline platform directly. Your client collects and then encrypts the required customer information. It then sends this encrypted information to your server, where you add all other relevant information and submit a payment request to the Worldline platform.
• Use a Server SDK to build a payment flow hosted on your server.
  In this case, you can use the Server SDK to obtain the payment products that are applicable to the payment, to obtain the fields that need to be collected from the customer for a selected payment product, and to submit the payment request itself.

In the next couple of paragraphs, we discuss each of these options in more detail.

Use a hosted payment through the MyCheckout hosted payment pages (RPP)

The high-level flow of a hosted payment is described below, followed by a more detailed look at each of the steps.

1. At this point, your customer has provided all relevant information regarding the order, e.g. a shopping cart of items and a shipping address.
2. See the section on initialization. Use connect-sdk-nodejs to create an instance of connectSdk if you hadn't done so yet, and set the metadata that you've collected about the client of the customer.
3. Create a CreateHostedCheckoutRequest body and populate at least its Order. See the relevant section of the full API reference for more details. You can specify an optional returnUrl, which is used to redirect your customer back to your website in step 9.
4. The create hosted checkout SDK call returns a CreateHostedCheckoutResponse response. Store the hostedCheckoutId and RETURNMAC it contains, as well as any other relevant order information. You will need these when your customer returns from our hosted payment pages, or when the customer fails to return in a reasonable amount of time. Now take response.partialRedirectUrl and prepend "https://yoursubdomain" to it to create hostedCheckoutUrl, where yoursubdomain is an RPP subdomain you requested. You can find your subdomains in the Configuration Center's Payment Page Setup tab, under the Subdomain settings of your merchant. If you are logged in as an adminstrator, you can request a subdomain here as well.
5. After completing the interactive payment process in the RPP, your customer is redirected back to the url you provided in step 3 as body.hostedCheckoutSpecificInput.returnUrl. The hostedCheckoutId and RETURNMAC you stored in step 5 are added to this URL as query parameters. Specifying a returnUrl is optional, however. As a result, your customer is only redirected back if you've provided a URL in step 3.
6. If you cannot identify the customer based on e.g. the HTTP session, you can use the hostedCheckoutId for this purpose. If you do, you must check that the hostedCheckoutId and RETURNMAC from the returnUrl match those that you stored in step 3. Note that the RETURNMAC is used as a shared secret between the Worldline platform and your system that is specific for this hosted checkout.
7. Retrieve the results of the customer's interaction with the Worldline platform.
8. Check the GetHostedCheckoutResponse response returned in step 13. If response.status equals PAYMENT_CREATED, then the customer attempted a payment, the details of which can be found in response.createdPaymentOutput. Depending on the payment product chosen and the status of the payment you can "deliver the goods" immediately, or set up a regular poll of the created payment to wait for the status. Such a poll is done using the SDK call client.v1.payments.get(merchantId, paymentId), where paymentId is in the response of client.v1.payments.create(merchantId, createPaymentStub, paymentContext). For details on the various payment products and their statuses, see Payment Products.

Additionally, it may be the case that the customer does not return in time (or at all), for example because the browser is closed or because you didn't provide a returnUrl. In this case, you need to retrieve the status of the hosted checkout (step 12) before the hosted checkout times out, which happens after 2 hours, and follow step 14 as well.

Use a Client SDK to build a payment flow for a native app or a JavaScript application

The high-level flow of a payment performed with a native app or a JavaScript application is described below, followed by a more detailed look at each of the steps. First, we discuss the flow for payment products that do not require a redirect to a payment method hosted by a third party. Afterwards, the flow for payment methods that require a redirect is described.

Although this flow uses the Client SDK, we won't go into the details of this SDK here. A detailed description is given in the documentation of the Client SDK.

1. At this point, your customer has provided all relevant information regarding the order, e.g. a shopping cart of items and a shipping address.
2. The app sends the metadata about the client of the customer and the order information to your server.
3. See the section on initialization. Use connect-sdk-nodejs to create an instance of connectSdk if you hadn't done so yet, and set the metadata about the client of the customer provided in the previous step.
4. Create a SessionRequest body and request a new session. By creating a session, you allow your consumer to communicate with our Client API via your app. See the relevant section of the full API reference for more details. Requesting a new session results in a SessionResponse response, which contains a clientSessionId, customerId, and a region. Store the relevant information to be able to link the order and customer to the payment.
5. Send the clientSessionId, customerId, and region to the app. The Client SDK needs this information to interact with the Client API. As mentioned above, the documentation of the Client SDK provides additional details.
6. Once the interactive payment process is finished, the app has to send the encodedClientMetaInfo, encryptedFields, and paymentProductId to your server. The encryptedFields contains confidential information about the payment request. Do not store it anywhere. Use the paymentProductId to determine which additional fields you need to provide in the payment request. Some of these fields may come from your app, so you can decide to send additional app-specific data to your server. For payments that require a redirect to a third party, for example, you could send a return URL as app-specific data. Note that for this flow, we assume that we're dealing with a payment that doesn't require a redirect.
7. Create a CreatePaymentRequest body. Populate its encryptedCustomerInput with the encryptedFields obtained from the app. Also populate its Order. You may also want to populate the fraudFields and the relevant PaymentMethodSpecificInput. To this end, you can map the paymentProductId obtained from the app to its payment method. For example, for a card payment, you can populate cardPaymentMethodSpecificInput to e.g. set a customerReference or indicate that the payment is the first of a recurring sequence.
8. Use the body you just created to perform a create payment request. See the relevant section of the full API reference for more details. The create payment SDK call returns a CreatePaymentResponse response. The status of the payment is accessible via response.payment.status. Depending on the payment product chosen and the status of the payment you can "deliver the goods" immediately, or set up a regular poll of the created payment to wait for the status. Such a poll is done using the SDK call client.v1.payments.get(merchantId, paymentId), where paymentId is in the response of client.v1.payments.create(merchantId, createPaymentStub, paymentContext). For details on the various payment products and their statuses, see Payment Products.

The high-level flow of a payment performed with a native app or a JavaScript application is a little different if a redirect is involved. We only describe the steps that differ from the flow without a redirect.

1. The payment process shown in the diagram above involves a redirect of your customer. For this example, we assume that the app decides which returnUrl should be used, which is sent as part of the app-specific data. Your customer is redirected to this URL (i.e., is send back to your app) after completing the payment process. The paymentProductId can be used to determine whether we're dealing with a payment that involves a redirect.
2. Create a CreatePaymentRequest body and populate its encryptedCustomerInput and its Order. Additionally, populate its redirectPaymentMethodSpecificInput by providing at least the desired returnUrl. See the relevant section of the full API reference for more details.
3. The create payment SDK call returns a CreatePaymentResponse response. For payments involving a redirect, response.merchantAction.redirectData.redirectURL defines the URL to which the customer should be redirected to complete the payment. You need to store the value ofresponse.merchantAction.redirectData.RETURNMAC because it should be compared with theRETURNMAC returned by the app at a later stage. Additionally, you need to store the value ofresponse.payment.id. This paymentId is needed to check the status of the payment after the redirect.
4. Send the redirectUrl to your app so that it can redirect the customer to the payment page hosted by the third party.
5. After the payment process is completed, your customer is redirected to the returnUrl specified previously. In the flow shown in the figure above, we assume that this URL brings the customer back to the app.
6. The app should retrieve the RETURNMAC from the returnUrl and send it to your server.
7. You can use the RETURNMAC to identify the customer by comparing it with the one stored previously, and to validate that the customer was redirected to you by our systems.
8. Use the paymentId stored previously to check the status of the payment. See the relevant section of the full API reference for more details. The retrieve payment SDK call returns a PaymentResponse response. The status of the payment is accessible via response.payment.status. Use this status to handle the order appropriately, as described above.

Use a Server SDK to build a payment flow hosted on your server

The high-level flow of a payment performed from pages hosted on your server is described below, followed by a more detailed look at each of the steps. First, we describe the flow for payment products that do not require a redirect to a payment method hosted by a third party. Afterwards, the flow for payment methods that require a redirect is described.

1. At this point, your customer has provided all relevant information regarding the order, e.g. a shopping cart of items and a shipping address.
2. See the section on initialization. Use connect-sdk-nodejs to create an instance of connectSdk if you hadn't done so yet, and set the metadata that you've collected about the client of the customer.
3. Create FindParams queryParams and request a list of relevant payment products. See the relevant section of the full API reference for more details.
4. Show the relevant payment products to the customer such that he or she can select one.
5. The customer selects one of available the payment products.
6. Once the customer has decided which payment product should be used, you request the fields of this payment product. See the relevant section of the full API reference for more details.
7. Based on the information retrieved in the previous step, you render a form that the customer can use to enter all relevant information for the selected payment product.
8. The customer submits the form.
9. Create a CreatePaymentRequest body, populate its Order and other properties depending on the selected payment product, and submit it. See the relevant section of the full API reference for more details. Do not store the information provided by the customer. The paymentProductId can be used to determine whether this payment involves a redirect to a third party. For this flow, we assume that we're dealing with a payment that doesn't require a redirect.
10. The create payment SDK call returns a CreatePaymentResponse response. The status of the payment is accessible via response.payment.status. Depending on the payment product chosen and the status of the payment you can "deliver the goods" immediately, or set up a regular poll of the created payment to wait for the status. Such a poll is done using the SDK call client.v1.payments.get(merchantId, paymentId), where paymentId is in the response of client.v1.payments.create(merchantId, createPaymentStub, paymentContext). For details on the various payment products and their statuses, see Payment Products.

The high-level flow of a payment performed from pages on your server is a little different if a redirect is involved. We only describe the steps that differ from the flow without a redirect.

1. We assume that we're dealing with a payment that involves a redirect. As mentioned above, this can be determined using the paymentProductId. Create a CreatePaymentRequest body and populate at least its Order. Additionally, populate its redirectPaymentMethodSpecificInput by providing at least the desired returnUrl. The returnUrl defines the location to which the customer should be redirected after completing the payment process. See the relevant section of the full API reference for more details.
2. The create payment SDK call returns a CreatePaymentResponse response. For payments involving a redirect, response.merchantAction.redirectData.redirectURL defines the URL to which the customer should be redirected to complete the payment. You need to store the value ofresponse.merchantAction.redirectData.RETURNMAC because it should be compared with theRETURNMAC returned by the third party at a later stage. Additionally, you need to store the value ofresponsepayment().id. This paymentId is needed to check the status of the payment after the redirect.
3. Redirect the customer to the redirectUrl.
4. After the payment process is completed, your customer is redirected to the returnUrl specified previously. In the flow shown in the figure above, we assume that this URL brings the customer back to your server.
5. Retrieve the RETURNMAC provided by the third party from the returnUrl. You can use the RETURNMAC to identify the customer by comparing it with the one stored previously, and to validate that the customer was redirected to you by our systems.
6. Use the paymentId stored previously to check the status of the payment. See the relevant section of the full API reference for more details. The retrieve payment SDK call returns a PaymentResponse response. The status of the payment is accessible via response.payment.status. Use this status to handle the order appropriately, as described above.

File Service support

Uploading files

To upload a file, you need to add the file as an object with the following properties:

• fileName: the name of the file (without any path).
• content: the content of the file, as a Readable Stream , Buffer or string.
• contentType: the content type, e.g. application/pdf. Please check the API references for the allowed formats. You can find an incomplete list of content types (also called MIME types) here .

Downloading files

Downloading files is very similar to other calls. The only difference is in the response - for downloaded files, the body property of the response is a Readable Stream , and the response contains an extra file property, which is an object with the following properties:

• contentType: the file's content type.
• contentLength: the file's content length, if available.
• filename: the filename as retrieved from the Content-Disposition, if available.

To read from the response body, you should either listen to its data and end events, or use its pipe method to send the file content to a Writable Stream .

Idempotent requests

To execute a request as an idempotent request, you can call the same method as for a non-idempotent request, but with an extra paymentContext argument with its idempotence property set. This will make sure the SDK will send an X-GCS-Idempotence-Key header with the idempotence key as its value.

If a subsequent request is sent with the same idempotence key, the response will contain an X-GCS-Idempotence-Request-Timestamp header, and the SDK will set the requestTimestamp property of the idempotence object of the PaymentContext argument so it's available in the response. If the first request has not finished yet, the RESTful Server API will return a 409 status code.
For example:

paymentContext.idempotence = {
  key: "[idempotence-key]"
};
const sdkResponse = await client.v1.payments.create(merchantId, createPaymentStub, paymentContext);
render(res, sdkResponse);
if (paymentContext.idempotence.requestTimestamp) {
  // this call is made with idempotence annd is still being handled
  console.log("idempotence timestamp", paymentContext.idempotence.requestTimestamp)
};

Errors

Payment errors

If a payment attempt is declined by the RESTful Server API, the response's isSuccess property will be false. The body contains a reference to the payment result which can be inspected to find the reason why the payment attempt was declined. This payment result can also be used to later retrieve the payment attempt again.
For example:

function render(res, response) {
  if (!response.isSuccess) {
    console.log(response, response.body);
    const status = error.status;
    const body = error.body;
    res.status(status).json(body).end();
  }
}

Error overview

The following table is a summary that shows when each of these errors will be returned:

Logging

The Node.js SDK supports logging of requests, responses and errors of the API communication.

In order to start using the logging feature, an implementation of the Logger interface should be provided. The example app provides an example implementations for logging.

Logging can be enabled by setting the enableLogging property when initializing a Client object, and providing the logger as an argument logger. Alternatively, it can be enabled on an existing Client by calling client.context.setEnableLogging(true).

Advanced use: Customization of the communication

A Client uses an http.Agent to communicate with the RESTful Server API. By default Node.js will provide the http.Agent. If needed you can provide your own instance instead. For instance, https-proxy-agent can be used to provide proxying using the HTTP CONNECT method :

import { HttpsProxyAgent } from "https-proxy-agent";

const client = connectSdk.init({
  host: "[hostname.of.the.api]",
  scheme: "https",
  port: 443,
  enableLogging: true, // defaults to false
  logger: logger, // if undefined console.log will be used
  apiKeyId: "[your-api-key-id]",
  secretApiKey: "[your-secret-api-key]",
  integrator: "[your-company-name]",
  connectionOptions: {
    agent: new HttpsProxyAgent("[url.of.the.proxy]")
  }
});