> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/sdks/nodejs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Node.js

## Introduction

The Mangopay Node.js SDK makes working with the Mangopay API easier in a Node.js environment.

The SDK package is available on npm: [mangopay4-nodejs-sdk](https://www.npmjs.com/package/mangopay4-nodejs-sdk)

> **Warning**
>
> **Caution – Use only the mangopay4 package (late Nov 2025)**
>
> Please ensure you use **only** the package with **mangopay4** in the name (this is the package name and has no connection with the SDK version number).
>
> **Any other package must not be used.** You need to update your package manually.
>
> Since November 25, 2025, Mangopay's official SDKs are no longer accessible on GitHub (with the exception of PHP for publication reasons).

> **Info**
>
> **Prerequisites**
>
> To run the Mangopay Node.js SDK, you’ll need:
>
> * A `ClientId` and an API key – if you don't have these, [contact Sales](https://mangopay.com/contact) to get access to the [Mangopay Dashboard](https://hub.mangopay.com/)
> * Node.js installed (v.14 and higher)
> * npm package manager installed

> **Note**
>
> **Note - Mangopay SDK compatibility**
>
> The Node.js SDK is only compatible with the v2.01 version of the Mangopay API.

## Getting started

1. Install the SDK

```javascript
npm install mangopay4-nodejs-sdk --save 
```

2. Initialize the SDK

```javascript
const mangopay = require('mangopay4-nodejs-sdk');

const paymentApi = new mangopay({
    clientId: 'your-mangopay-client-id',
    clientApiKey: 'your-mangopay-api-key',
    baseUrl: 'https://api.sandbox.mangopay.com'
});
```

The configuration object of the SDK supports all the following properties:

<table>
  <thead>
    <tr>
      <th class="header">
        Key
      </th>

      <th class="header">
        Type
      </th>

      <th class="header">
        Default value
      </th>

      <th class="header">
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `clientId`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `null`
      </td>

      <td class="table-content">
        Your Mangopay ClientId – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `clientApiKey`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `null`
      </td>

      <td class="table-content">
        Your Mangopay API key – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `baseUrl`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        http

        ://

        api.sandbox.mangopay.com/
      </td>

      <td class="table-content">
        The API sandbox URL. Set to the sandbox environment by default. To enable production environment, set it to http

        ://

        api.mangopay.com/
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `debugMode`
      </td>

      <td class="table-content">
        boolean
      </td>

      <td class="table-content">
        `false`
      </td>

      <td class="table-content">
        Activates the debug mode. Recommended only in Sandbox.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `logClass`
      </td>

      <td class="table-content" />

      <td class="table-content">
        `function() {console.log(arguments)}`
      </td>

      <td class="table-content">
        `function() {console.log(arguments)}`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `connectionTimeout`
      </td>

      <td class="table-content">
        integer
      </td>

      <td class="table-content">
        `30000`
      </td>

      <td class="table-content">
        Set the time to wait (in milliseconds) while trying to establish a connection before terminating the attempt and generating an error.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `responseTimeout`
      </td>

      <td class="table-content">
        integer
      </td>

      <td class="table-content">
        `80000`
      </td>

      <td class="table-content">
        Set response timeout limit (in milliseconds).
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `apiVersion`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        v2.01
      </td>

      <td class="table-content">
        The API version.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `errorHandler`
      </td>

      <td class="table-content">
        null
      </td>

      <td class="table-content">
        `function(options, err) {console.error(options, err)}`
      </td>

      <td class="table-content">
        Set a custom error handler.
      </td>
    </tr>
  </tbody>
</table>

## SDK usage

All endpoints are documented with the related Node.js SDK method throughout the Mangopay documentation. The code examples provided should be adjusted for your usage.

### TypeScript

The SDK is compatible with TypeScript and provides a set of predefined models. They are available in the `/lib/models/` folder.

### Using callbacks instead of promises

Across the Mangopay endpoint documentation, the usage of the SDK is documented with promises. If you prefer callbacks, here is an example on how to use them:

```javascript
const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
  clientId: 'your-client-id',
  clientApiKey: 'your-api-key',
})

let user = {
  Id: '171602348',
}

mangopay.Users.get(user.Id, function(data, response, err){
	console.log(data)
	console.log(response)
	console.log(err)
})
```

### Pagination and filtering

For endpoints that support [pagination](/api-reference/overview/pagination) and [filtering](/api-reference/overview/filtering-sorting), you can use `options.parameters` to specify these options:

```javascript
const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
  clientId: 'your-client-id',
  clientApiKey: 'your-api-key',
})

let parameters = {
  // Options for pagination
  per_page: 2,
  page: 2,

  // Options for Filters
  BeforeDate: 1683129820,
  AfterDate: 1682957020,
  // Nature: REGULAR,
  // Status: FAILED,
  // Type: TRANSFER,
};

const indexEvents = async () => {
  return await mangopay.Events.getAll({ parameters: parameters })
    .then((response) => {
      console.info(response)
      return response;
    })
    .catch((err) => {
      console.log(err)
      return false;
    });
};

indexEvents()
```

### Accessing response headers

For reading the server response headers, you can use resolveWithFullResponse. This is useful to access information about the [pagination](/api-reference/overview/pagination) or [rate limiting](/api-reference/overview/rate-limiting).

```javascript
const mangopayInstance = require('mangopay4-nodejs-sdk')
const mangopay = new mangopayInstance({
  clientId: 'your-client-id',
  clientApiKey: 'your-api-key',
})

const indexEvents = async () => {
  return await mangopay.Events.getAll({ resolveWithFullResponse: true })
    .then((response) => {
      console.info(response.headers['x-number-of-pages'])
      return response
    })
    .catch((err) => {
      console.log(err)
      return false
    });
};

indexEvents()
```

## Error handling

The SDK provides a default `errorHandler` in the configuration that prints any HTTP errors returned by the API to console. You can overwrite this with your own logic for global exception handling.

For a given function, you can use a `.catch(error)` to define specific logic, for example:

```javascript
api.Recipients.validate(recipient, userId).then(function (data) {
   done();
})
   .catch(function (error) {
       errorResult = error;
	 // your custom logic
   });
```