Awesome

Adyen API library for Node.js

This is the official Adyen API library for Node.js that we recommend for integrating with Adyen APIs.

Supported APIs

This library supports the following:

Supported Webhook versions

The library supports all webhooks under the following model directories:

For more information, refer to our documentation or the API Explorer.

Before you begin

Before you begin to integrate:

• Create an Adyen test account.
• Set up your API credentials.
• Install Node.js version 18 or later.

Installation

Install the Node.JS package:

npm install --save @adyen/api-library

Alternatively, you can download the release on GitHub.

Updating

To update the Node.JS package:

npm update @adyen/api-library

Check for breaking changes on the releases page.

Usage

// Step 1: Require the parts of the module you want to use
const { Client, CheckoutAPI} = require('@adyen/api-library');

// Step 2: Initialize the client object
const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"}); 

// Step 3: Initialize the API object
const checkoutApi = new CheckoutAPI(client);

// Step 4: Create the request object
  const paymentRequest = {
    amount: {
      currency: "USD",
      value: 1000 // value in minor units
    },
    reference: "Your order number",
    paymentMethod: {
      type: "scheme",
      encryptedCardNumber: "test_4111111111111111",
      encryptedExpiryMonth: "test_03",
      encryptedExpiryYear: "test_2030",
      encryptedSecurityCode: "test_737"
    },
    shopperReference: "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
    storePaymentMethod: true,
    shopperInteraction: "Ecommerce",
    recurringProcessingModel: "CardOnFile",
    returnUrl: "https://your-company.com/...",
    merchantAccount: "YOUR_MERCHANT_ACCOUNT"
  };
  
// Step 5: Make the request
checkoutApi.PaymentsApi.payments(paymentRequest)
  .then(paymentResponse => console.log(paymentResponse.pspReference))
  .catch(error => console.log(error));

If you want to pass query string parameters, you can use the params field from IRequest (also used for idempotency-key and other header fields). The method descriptions contain an example of the possible values you can send to the API for the query parameters, just as stated in the API explorer.

const requestOptions: IRequest.Options = {
    params: {
        limit: "5",
        offset: "10"
    }
};
await balancePlatformService.AccountHoldersApi.getAllBalanceAccountsOfAccountHolder("AH32272223222B5CM4MWJ892H", requestOptions);

Step 1: Require the parts of the module you want to use

Use the Node.js require function to load the Client and API objects from the Adyen module. For the name of the API objects, see Supported APIs.

For example, to use the Checkout API:

const { Client, CheckoutAPI} = require('@adyen/api-library');

Step 2: Initialize the client object

Initialize the client object, passing the following:

• apiKey: The API key you generated from the Customer Area.
• environment: For the test environment, use TEST. For the live environment, use LIVE.

For example:

const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"}); 

Step 3: Initialize the API object

Initialize the API object you want to use, passing the client object from the previous step.

For example, for the Checkout API:

const checkoutApi = new CheckoutAPI(client);

Step 4: Create the request object

Create a the request object. For example, for a request to the /payments endpoint:

  const paymentRequest = {
    amount: {
      currency: "USD",
      value: 1000 // value in minor units
    },
    reference: "Your order number",
    paymentMethod: {
      type: "scheme",
      encryptedCardNumber: "test_4111111111111111",
      encryptedExpiryMonth: "test_03",
      encryptedExpiryYear: "test_2030",
      encryptedSecurityCode: "test_737"
    },
    shopperReference: "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
    storePaymentMethod: true,
    shopperInteraction: "Ecommerce",
    recurringProcessingModel: "CardOnFile",
    returnUrl: "https://your-company.com/...",
    merchantAccount: "YOUR_MERCHANT_ACCOUNT"
  };

Step 5: Make the request

Use the API object's method to make the request. For example, to make a request to the /payments endpoint using the CheckoutAPI object:

checkoutApi.PaymentsApi.payments(paymentRequest)
  .then(paymentResponse => console.log(paymentResponse.pspReference))
  .catch(error => console.log(error));

Client setup when going live

For APIS that require your Live URL Prefix (Binlookup, BalanceControl, Checkout, Payout and Recurring) the client is set up as follows in order to start processing live payments:

const { Client } = require('@adyen/api-library');

const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST", liveEndpointUrlPrefix: "YOUR_LIVE_URL_PREFIX"}); 

Usage in TypeScript

Alternatively, you can use the Types included in this module for Typescript and async syntax.

  const { Client, CheckoutAPI, Types } = require('@adyen/api-library');
  const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"});

  const makePaymentsRequest = async () => {
    const paymentsRequest : Types.checkout.PaymentRequest = {
      amount: {
        currency: "USD",
        value: 1000 // Value in minor units.
      },
      reference: "Your order number",
      paymentMethod: {
        type: Types.checkout.CardDetails.TypeEnum.Scheme,
        encryptedCardNumber: "test_4111111111111111",
        encryptedExpiryMonth: "test_03",
        encryptedExpiryYear: "test_2030",
        encryptedSecurityCode: "test_737"
      },
      shopperReference: "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
      storePaymentMethod: true,
      shopperInteraction: Types.checkout.PaymentRequest.ShopperInteractionEnum.Ecommerce,
      recurringProcessingModel: Types.checkout.PaymentRequest.RecurringProcessingModelEnum.CardOnFile,
      returnUrl: "https://your-company.com/...",
      merchantAccount: "YOUR_MERCHANT_ACCOUNT"
    };
    const checkoutAPI = new CheckoutAPI(client);
    const paymentResponse : Types.checkout.PaymentResponse = await checkoutAPI.PaymentsApi.payments(paymentsRequest);
    console.log(paymentResponse.pspReference);
  }

  makePaymentsRequest();

Deserializing JSON Strings

In some setups you might need to deserialize JSON strings to request objects. For example, when using the libraries in combination with Dropin/Components. Please use the built-in deserialization functions:

// Import the required model class
import { checkout } from "../typings";

// Deserialize using built-in ObjectSerializer class
const requestJson: JSON = JSON.parse(`YOUR_JSON_STRING`);
const paymentRequest: checkout.PaymentRequest = await checkout.ObjectSerializer.deserialize(requestJson,"PaymentRequest");

Custom HTTP client configuration

By default, Node.js https is used to make API requests. Alternatively, you can set a custom HttpClient for your Client object.

For example, to set axios as your HTTP client:

const {Client, Config} = require('@adyen/api-library');
const axios = require("axios");
// ... more code
const config = new Config();
const client = new Client({
  config,
  httpClient: {
    async request(endpoint, json, config, isApiKeyRequired, requestOptions) {
        const response = await axios({
            method: 'POST',
            url: endpoint,
            data: JSON.parse(json),
            headers: {
                "X-API-Key": config.apiKey,
                "Content-type": "application/json"
            },
        });

        return response.data;
    }
  }
});
// ... more code

Parsing and Authenticating Banking Webhooks

Parse an AccountHolderNotificationRequest webhook;

let bankingWebhookHandler = new BankingWebhookHandler(YOUR_BANKING_WEBHOOK);
const accountHolderNotificationRequest: AccountHolderNotificationRequest = bankingWebhookHandler.getAccountHolderNotificationRequest();
const genericWebhook = bankingWebhookHandler.getGenericWebhook();

You can also parse the webhook with a generic type, in case you do not know the webhook type in advance. In this case you can check the instance of the webhook in order to parse it to the respective type (or just use it dynamically);

let bankingWebhookHandler = new BankingWebhookHandler(YOUR_BANKING_WEBHOOK);
const genericWebhook = bankingWebhookHandler.getGenericWebhook();

Verify the authenticity (where you retrieve the hmac key from the CA and the signature from the webhook header);

const isValid = hmacValidator.validateBankingHMAC("YOUR_HMAC_KEY", "YOUR_HMAC_SIGNATURE", jsonString)

Management Webhooks

Management webhooks are verified the exact same way as the banking webhooks. To parse them however, instead you use:

let managementWebhookHandler = new ManagementWebhookHandler(YOUR_MANAGEMENT_WEBHOOK);
const genericWebhook = managementWebhookHandler.getGenericWebhook();

Proxy configuration

To configure a proxy connection, set the proxy property of your HttpURLConnectionClient object.

For example:

const {HttpURLConnectionClient, Client, Config} = require('@adyen/api-library');
// ... more code
const config = new Config();
const client = new Client({ config });
const httpClient = new HttpURLConnectionClient();
httpClient.proxy = { host: "http://google.com", port: 8888,  };

client.setEnvironment('TEST');
client.httpClient = httpClient;

// ... more code

Using the Cloud Terminal API Integration

In order to submit In-Person requests with Terminal API over Cloud you need to initialize the client in a similar way as the steps listed above for Ecommerce transactions, but make sure to include TerminalCloudAPI:

// Step 1: Require the parts of the module you want to use
const {Client, TerminalCloudAPI} from "@adyen/api-library";

// Step 2: Initialize the client object
const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"});

// Step 3: Initialize the API object
const terminalCloudAPI = new TerminalCloudAPI(client);

// Step 4: Create the request object
const serviceID = "123456789";
const saleID = "POS-SystemID12345";
const POIID = "Your Device Name(eg V400m-123456789)";

// Use a unique transaction for every transaction you perform
const transactionID = "TransactionID";
const paymentRequest: SaleToPOIRequest = {
    MessageHeader: {
        MessageClass: MessageClassType.Service,
        MessageCategory: MessageCategoryType.Payment,
        MessageType: MessageType.Request,
        ProtocolVersion: "3.0",
        ServiceID: serviceID,
        SaleID: saleID,
        POIID: POIID
    },
    PaymentRequest: {
        SaleData: {
            SaleTransactionID: {
                TransactionID: transactionID,
                TimeStamp: this.GetDate().toISOString()
            },

            SaleToAcquirerData: {
                applicationInfo: {
                    merchantApplication: {
                        version: "1",
                        name: "test",
                    }
                }
            }
        },
        PaymentTransaction: {
            AmountsReq: {
                Currency: "EUR",
                RequestedAmount: 1000
            }
        }
    }
};

// Step 5: Make the request
const terminalAPIResponse: terminal.TerminalApiResponse = await terminalCloudAPI.sync(paymentRequest);

Optional: perform an abort request

To perform an abort request you can use the following example:

const abortRequest: SaleToPOIRequest = {
    MessageHeader: {
        MessageClass: MessageClassType.Service,
        MessageCategory: MessageCategoryType.Abort,
        MessageType: MessageType.Request,
        ProtocolVersion: "3.0",
        // Different serviceID than the one you're aborting
        ServiceID: "Different service ID",
        SaleID: saleID,
        POIID: POIID
    },
    AbortRequest: {
        AbortReason: "MerchantAbort",
        MessageReference: {
            MessageCategory: MessageCategoryEnum.Payment,
            SaleID: saleID,
            // Service ID of the payment you're aborting
            ServiceID: serviceID,
            POIID: POIID
        }

    }
};
const terminalAPIResponse: terminal.TerminalApiResponse = await terminalCloudAPI.sync(abortRequest);

Optional: perform a status request

To perform a status request you can use the following example:

const statusRequest: SaleToPOIRequest = {
    MessageHeader: {
        MessageClass: MessageClassType.Service,
        MessageCategory: MessageCategoryType.TransactionStatus,
        MessageType: MessageType.Request,
        ProtocolVersion: "3.0",
        ServiceID: "Different service ID",
        SaleID: saleID,
        POIID: POIID
    },
    TransactionStatusRequest: {
        ReceiptReprintFlag: true,
        DocumentQualifier: [DocumentQualifierEnum.CashierReceipt, DocumentQualifierEnum.CustomerReceipt],
        MessageReference: {
            SaleID: saleID,
            // serviceID of the transaction you want the status update for
            ServiceID: serviceID,
            MessageCategory: MessageCategoryEnum.Payment
        }
    }
};
const terminalAPIResponse: terminal.TerminalApiResponse = await terminalCloudAPI.sync(statusRequest);

Using the Local Terminal API Integration

The procedure to send In-Person requests using Terminal API over Local Connection is similar to the Cloud Terminal API one, however, additional encryption details are required to perform the requests. Make sure to install the certificate as described here

// Step 1: Require the parts of the module you want to use
const {Client, TerminalLocalAPI} from "@adyen/api-library";

// Step 2: Add your Certificate Path and Local Endpoint to the config path. Install the certificate and save it in your project folder as "cert.cer"
const config: Config = new Config();
config.certificatePath = "./cert.cer";
config.terminalApiLocalEndpoint = "The IP of your terminal (eg https://192.168.47.169)";
config.apiKey = "YOUR_API_KEY_HERE";

// Step 3: Setup a security password for your terminal in CA, and import the security key object:
const securityKey: SecurityKey = {
    AdyenCryptoVersion: 1,
    KeyIdentifier: "keyIdentifier",
    KeyVersion: 1,
    Passphrase: "passphrase",
};

// Step 4 Initialize the client and the API objects
client = new Client({ config });
const terminalLocalAPI = new TerminalLocalAPI(client);

// Step 5: Create the request object
const paymentRequest: SaleToPOIRequest = {
// Similar to the saleToPOIRequest used for Cloud API
}

// Step 6: Make the request
const terminalApiResponse: terminal.TerminalApiResponse = await terminalLocalAPI.request(paymentRequest, securityKey);

Using the Local Terminal API Integration without Encryption (Only on TEST)

If you wish to develop the Local Terminal API integration parallel to your encryption implementation, you can opt for the unencrypted version. Be sure to remove any encryption details from the CA terminal config page.

// Step 1: Require the parts of the module you want to use
const {Client, TerminalLocalAPIUnencrypted} from "@adyen/api-library";

// Step 2: Add your Certificate Path and Local Endpoint to the config path. Install the certificate and save it in your project folder as "cert.cer"
const config: Config = new Config();
config.terminalApiLocalEndpoint = "The IP of your terminal (eg https://192.168.47.169)";
config.apiKey = "YOUR_API_KEY_HERE";

// Step 3 Initialize the client and the API objects
client = new Client({ config });
const terminalLocalAPI = new TerminalLocalAPIUnencrypted(client);

// Step 4: Create the request object
const paymentRequest: SaleToPOIRequest = {
// Similar to the saleToPOIRequest used for Cloud API
}

// Step 5: Make the request
const terminalApiResponse: terminal.TerminalApiResponse = await terminalLocalAPI.request(paymentRequest);

Feedback

We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out our feedback form to share your thoughts, suggestions or ideas.

Example integration

Clone our Node.js example integration to see how the Adyen API library for Node.js can be used. The integration includes code comments that highlight key features and concepts.

Contributing

We strongly encourage you to contribute to this repository by:

• Adding new features and functionality.
• Fixing bugs and issues.
• Making general improvements.

To learn how to create a pull request, read our contribution guidelines.

Support

To request a feature, report a bug, or report a security vulnerability, create a GitHub issue.

For other questions, contact our support team.

License

This repository is available under the MIT license.

See also

• Example integration