@adyen/api-library

Adyen Node.js API Library

This is the officially supported NodeJS library for using Adyen's APIs.

Supported API versions

The Library supports all APIs under the following services:

API	Description	Service Name	Supported version
BIN lookup API	The BIN Lookup API provides endpoints for retrieving information based on a given BIN.	BinLookup	v52
Checkout API	Our latest integration for accepting online payments.	CheckoutAPI	v70
Configuration API	The Configuration API enables you to create a platform where you can onboard your users as account holders and create balance accounts, cards, and business accounts.	BalancePlatform	v2
DataProtection API	Adyen Data Protection API provides a way for you to process Subject Erasure Requests as mandated in GDPR. Use our API to submit a request to delete shopper's data, including payment details and other related information (for example, delivery address or shopper email)	DataProtection	v1
Legal Entity Management API	Manage legal entities that contain information required for verification.	LegalEntityManagement	v2
Local/Cloud-based Terminal API	Our point-of-sale integration.	TerminalLocalAPI or TerminalCloudAPI	-
Management API	Configure and manage your Adyen company and merchant accounts, stores, and payment terminals.	Management	v1
Payments API	Our classic integration for online payments.	ClassicIntegrationAPI	v68
Payouts API	Endpoints for sending funds to your customers.	Payout	v68
Platforms APIs	Set of APIs when using Adyen for Platforms. This API is used for the classic integration.	Platforms	-
Account API	Platforms subclass	Account	v6
Fund API	Platforms subclass	Fund	v6
Hosted onboarding API	Platforms subclass	HostedOnboardingPage	v6
Notification Configuration API	Platforms subclass	NotificationConfiguration	v6
Platforms Notifications Webhooks		Models only	v6
POS Terminal Management API	Endpoints for managing your point-of-sale payment terminals.	TerminalManagement	v1
Recurring API	Endpoints for managing saved payment details.	Recurring	v68
Stored Value API	Manage both online and point-of-sale gift cards and other stored-value cards.	StoredValue	v46
Transfers API	The Transfers API provides endpoints that can be used to get information about all your transactions, move funds within your balance platform or send funds from your balance platform to a transfer instrument.	Transfers	v3
Webhooks	Adyen uses webhooks to send notifications about payment status updates, newly available reports, and other events that can be subscribed to. For more information, refer to our documentation.	Models only	v1

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

Prerequisites

• Adyen test account. To start using Adyen APIs, you will need a Merchant Account.
• API key. For testing, your API credential needs to have the API PCI Payments role.
• Node 14 or higher

Installation

You can use NPM to add our library to your project

NPM

npm install --save @adyen/api-library

Alternatively, you can download the release on GitHub.

Upgrading

Please check the release page to check for breaking changes in Major versions.

Using the library

Client initialisation

General use with API key

Set up the client as a singleton resource; you can then use it to create service objects for the API calls that you make to Adyen:

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

General use with API key for live environment

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

General use with basic auth

  const { Client } = require('@adyen/api-library');
  const client = new Client({username: "YOUR_USERNAME", password: "YOUR_PASSWORD", environment: "TEST"});

Consuming Services

Every API the library supports is represented by a service object. The name of the service matching the corresponding API is listed in the Integrations section of this document.

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

  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"
  };
  const checkoutAPI = new CheckoutAPI(client);
  checkoutAPI.payments(paymentRequest)
    .then( paymentResponse => console.log(paymentResponse.pspReference))
    .catch(error => console.log(error));

Alternatively you can make use of the Types included in this library using Typescript, and/or use the async syntax:

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

  import { Types } from '@adyen/api-library';

  const doPaymentsRequest = async ()  => {
    const paymentRequest : 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.payments(paymentRequest);
    console.log(paymentResponse.pspReference);
  }

  doPaymentsRequest();

Custom HTTP Client Configuration

By default, NodeJS https will be used to submit requests to the API. But you can change that by injecting your own HttpClient on your client instance. In the example below, we use axios:

const {Client, Config} = require('@adyen/api-library');
const axios = require("axios");
...
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;
    }
  }
});
...

Proxy configuration

You can configure a proxy connection by injecting your own HttpURLConnectionClient on your client instance and changing the proxy setter value.

Example:

const {HttpURLConnectionClient, Client, Config} = require('@adyen/api-library');
...
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;
...

Example integration

For a closer look at how our NodeJS library works, clone our example integration. This includes commented code, highlighting key features and concepts, and examples of API calls that can be made using the library.

Contributing

We strongly encourage you to join us in contributing to this repository so everyone can benefit from:

• New features and functionality
• Resolved bug fixes and issues
• Any general improvements

Read our contribution guidelines to find out how to create a pull request.

Support

If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our support team.

Licence

This repository is available under the MIT license.

See also

• example integration