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

# IP allowlist

As well as authenticating your API calls using [OAuth 2.0 authentication](/api-reference/overview/authentication) and [mTLS authentication](/api-reference/overview/mtls), Mangopay requires all platforms to declare the IP addresses from which any API calls originate.

Declaring your IP addresses ensures that, in addition to being valid, authentication credentials are also being used from an expected and authorized source.

In the [Mangopay Dashboard](https://hub.mangopay.com/), your platform can declare and manage the IP addresses that your systems use, as described [below](#declaring-your-ip-addresses-to-mangopay).

This is distinct from the [IP addresses that Mangopay sends webhook notifications from](/webhooks#ip-addresses), which you may need to allowlist in your own firewall, in the opposite direction.

> **Warning**
>
> **Caution – Your IPs must be approved for each Client ID**
>
> You need to identify and add your IP addresses for each Client ID that you use – meaning both Production and Sandbox. Mangopay will approve your allowlist to ensure that configuration is correct before enforcement.
>
> Once the IP allowlist is enforced (as per timelines communicated via email), Mangopay will block traffic originating from any other sources. Failure to declare your IP addresses will result in service interruption.

## Understanding CIDR notation

Mangopay uses **CIDR (Classless Inter-Domain Routing) notation** to store your IP addresses in its allowlists. This notation makes it easier to identify a range of IPs.

Mangopay accepts both IPv4 and IPv6 formats.

For IPv6, Mangopay writes out the full format when saving your address, but you can declare the short format.

Note that it is not possible to add DNS names (e.g. `example.com`) or RFC 1918 private addresses (any IP address starting `10.`, `172.16.`, or `192.168.`), only public CIDR ranges.

### Single IP addresses

For a single address, Mangopay automatically saves it with the corresponding single-host CIDR notation. If you enter a single address in the Mangopay Dashboard, you'll see the prefix added automatically.

**IPv4** – The `/32` prefix is added to indicate a single IP. For example, `203.0.113.0` is saved as `203.0.113.0/32`.

**IPv6** – The `/128` prefix is added to indicate a single IP. For example, `2001:db8::10` (in short format) is saved as `2001:db8:0:0:0:0:0:10/128` (in long format).

### CIDR ranges

The CIDR range notation uses a prefix attached to the end of the starting address to indicate a range of consecutive addresses.

**IPv4**

For example, the prefix `/30` in IPv4 range contains exactly 4 IP addresses. If you enter `203.0.113.0/30`, you are automatically identifying these four specific hosts:

* `203.0.113.0`
* `203.0.113.1`
* `203.0.113.2`
* `203.0.113.3`

**IPv6**

Similarly, the prefix `/126` also contains exactly 4 IP addresses. If you enter `2001:db8::10/126` (in short format), you are automatically identifying these four specific hosts (in long format):

* `2001:db8:0:0:0:0:0:10`
* `2001:db8:0:0:0:0:0:11`
* `2001:db8:0:0:0:0:0:12`
* `2001:db8:0:0:0:0:0:13`

## IP allowlist limits

For security reasons, Mangopay applies limits to its IP allowlists.

### Maximum number of CIDR items

The allowlist uses items in [CIDR notation](#understanding-cidr-notation), meaning each item can represent either a single IP address or a block of consecutive addresses.

You can add a **maximum of 20 CIDR items** to a single allowlist, which applies to a single Client ID.

You can add the same CIDR item to more than one allowlist, so that it applies to more than one Client ID. This may be useful if your traffic for Production and Sandbox has the same IP address origin, or if you're running multiple Sandbox accounts.

### CIDR range limit per item

For each CIDR item in an allowlist, the size of the block is limited to the equivalent of 256 total addresses per item:

* **IPv4** – Allows prefixes from `/32` (1 address) up to `/24` (256 addresses)
* **IPv6** – Allows prefixes from `/128` (1 address) up to `/120` (256 addresses)

It is possible to add consecutive blocks to the list.

> **Check**
>
> **Best practice – Avoid broad ranges**
>
> When identifying your IP addresses, ensure that your list represents dedicated and controlled routes for your traffic. Avoid unnecessarily broad ranges.
>
> Typically, your system will route traffic through a stable Network Address Translation (NAT) gateway or other outgoing (egress) infrastructure. This results in a limited number of controlled public IP addresses that you can easily add to Mangopay's allowlist.

## Declaring your IP addresses to Mangopay

You need to identify all public IP addresses from which Mangopay-destined traffic can originate in your systems, both for Production and Sandbox.

To declare your IP address ranges to Mangopay, connect to the [Mangopay Dashboard](https://hub.mangopay.com/). The **Admin** or **Developer** role is required.

> **Note**
>
> **Note – IP allowlist applies to one Client ID**
>
> You need to declare IP addresses for each Client ID that you use in Production and Sandbox.
>
> Ensure you select the desired Client ID in the top-left environment selector before continuing.

### Add a new IP to your allowlist

For the given Client ID:

1. Navigate to ***Developers*** > ***IP allowlist***
2. Click ***Request addition to IP allowlist*** in the top right
3. Enter the IP address or CIDR block you wish to add and click ***Submit request***

Mangopay automatically uses [CIDR notation](#understanding-cidr-notation) for all IP items, whether v4 or v6, and saves v6 in the long format.

Once you submit your addition:

* The CIDR appears as `PENDING` on the ***IP allowlist*** tab
* The action (***ADD***) appears as `PENDING` on the ***Change requests*** tab

Mangopay reviews your IP address addition request to ensure there is no misconfiguration or security concern.

Once reviewed and approved, the CIDR range status in the ***IP allowlist*** tab becomes `ACTIVE`, indicating that it is allowed and can be used to send requests to the API.

In the event that your request is `REJECTED`, please contact Mangopay [via the Dashboard](https://hub.mangopay.com/) to discuss the reasons.

> **Note**
>
> **Note – Only approved requests allow traffic with the Client ID**
>
> Your IP addresses must be approved by Mangopay to be valid. When IP allowlisting is enforced, only requests from `APPROVED` addresses continue to reach Mangopay's servers for the given Production or Sandbox Client ID.
>
> API requests originating from IPs that are still `PENDING`, or for a different Client ID or environment, will be blocked.
>
> Kindly refer to email communications for details on enforcement timelines.

## Managing your allowlist

You need to manage your IP allowlist over time.

In the Dashboard (***Developers*** > ***IP allowlist***), there are two tabs:

* ***IP allowlist*** – Shows CIDR ranges that are `ACTIVE` (approved and valid), `PENDING`, or `DISABLED`. This tab allows you to take cancel and remove actions on existing items.
* ***Change requests*** – Shows actions taken on the IP allowlist to add or remove CIDRs.

In both cases, you can see the email address of the Dashboard user who last modified a range or requested the action, and the date.

> **Warning**
>
> **Caution – Anticipate changes in your IP addresses**
>
> Over time, you may need to update your IP allowlist by adding new ranges as per [the instructions above](#add-a-new-ip-to-your-allowlist).
>
> You must anticipate these changes to ensure your API requests can continue to reach Mangopay's servers. Failure to do so may result in blocked requests which impact your services.

### Cancel a pending change

If a change request is in the `PENDING` status, it can be canceled.

To do so:

1. Navigate to the ***IP allowlist*** tab
2. On the `PENDING` item in the allowlist, click the vertical three-dot icon (⋮)
3. Click ***Cancel request*** and confirm

The change request changes to `CANCELLED` on the ***Change requests*** tab. The effect on the ***IP allowlist*** tab depends on the action you are canceling:

* Canceling an **addition** removes the item from the allowlist, since it was never active.
* Canceling a **removal** reverts the item back to `ACTIVE`, since it was never disabled.

### Remove an obsolete CIDR

If you are no longer using an item on your IP allowlist, you can remove it.

To do so:

1. Navigate to the ***IP allowlist*** tab
2. On the `ACTIVE` item in the allowlist, click the vertical three-dot icon (⋮)
3. Click ***Remove*** and confirm

The removal action must be approved by Mangopay, so the item's status changes to `PENDING`. Once reviewed, the item's status changes to `DISABLED` if approved, or reverts to `ACTIVE` if rejected.

Once IP allowlisting is enforced for a Client ID, you cannot remove the last `ACTIVE` item from the allowlist. Add a replacement CIDR and wait for it to be approved before removing the obsolete one.