Skip to navigation
Overview

IP allowlist

As well as authenticating your API calls using OAuth 2.0 authentication and mTLS authentication, 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, your platform can declare and manage the IP addresses that your systems use, as described below.

This is distinct from the IP addresses that Mangopay sends webhook notifications from, which you may need to allowlist in your own firewall, in the opposite direction.

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, 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.

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. The Admin or Developer role is required.

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 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 to discuss the reasons.

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.

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.

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.