Skip to navigation

IP allowlist

As well as authenticating your API calls using OAuth 2.0 authentication, Mangopay requires all platforms to declare the IP addresses from which any API calls originate.

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

In the Mangopay Dashboard (Settings > Team & security > IP allowlist tab), your platform can add the IP addresses that your systems use to the allowlist, activate enforcement, and manage changes.

There is an IP allowlist for each Client ID in both Production and Sandbox environments.

Caution – Enforcement blocks traffic from non-allowed sources

Once you have added all IP addresses to your allowlist for a given Client ID, you can activate enforcement in the Dashboard.

When you activate enforcement, any API calls originating from sources not included in the CIDR ranges on the allowlist are refused and return a 403 - Forbidden HTTP error. API calls originating from IPs in the allowlist continue to reach Mangopay as before.

If your list does not comprehensively include all public IPs of all your systems that call Mangopay’s API endpoints, then your services could be inadvertently interrupted.

Mangopay is not responsible for any service disruption resulting from a misconfiguration of the IP allowlist feature.

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

Understanding CIDR notation

Mangopay uses Classless Inter-Domain Routing (CIDR) 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.

By design, Mangopay’s IP allowlist feature does not support dynamic or shared IP pools or serverless architecture without static public IPs, so you may need to review your setup.

Manage your IP allowlist

To declare your IP address ranges to Mangopay and manage your allowlist, connect to the Mangopay Dashboard.

The Admin role is required for all actions relating to the IP allowlist, whether for the Production Client ID or a Sandbox one.

Note – IP allowlist applies to one Client ID

You need to allow 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

To add a new IP address or CIDR range to your IP allowlist (requires Admin role):

  1. Ensure you have the desired Client ID selected in the top-left environment selector
  2. Navigate to Settings > Team & security > IP allowlist
  3. Under Add a trusted IP address, enter the IP address or CIDR block you wish to add and click Add to allowlist
  4. Enter all other IPs that send requests to Mangopay’s API endpoints

Once you add an IP, it appears in the list below.

Mangopay automatically uses CIDR notation for all IP items, whether v4 or v6, and saves v6 in the long format.

Activate your IP allowlist

By default, the IP allowlist is deactivated. When you have added all the necessary IPs, you can proceed to activation.

Caution – Enforcement blocks traffic from non-allowed sources

When you activate enforcement, any API calls originating from sources not included in the CIDR ranges on the allowlist are refused and return a 403 - Forbidden HTTP error. API calls originating from IPs in the allowlist continue to reach Mangopay as before.

If your list does not comprehensively include all public IPs of all your systems that call Mangopay’s API endpoints, then your services could be inadvertently interrupted.

Mangopay is not responsible for any service disruption resulting from a misconfiguration of the IP allowlist feature.

To activate your IP allowlist (requires Admin role):

  1. Ensure you have the desired Client ID selected in the top-left environment selector
  2. Navigate to Settings > Team & security > IP allowlist
  3. Ensure that the CIDR ranges comprehensively include all public IPs of all your public IPs for Mangopay-destined traffic
  4. Under Allowlist enforcement, click the toggle button
  5. Confirm the activation in the modal pop-up

Once confirmed, the toggle button shows as Active.

Delete an IP on your allowlist

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

To delete an IP from your allowlist (requires Admin role):

  1. Ensure you have the desired Client ID selected in the top-left environment selector
  2. Navigate to Settings > Team & security > IP allowlist
  3. Under Trusted IP addresses, identify the CIDR you wish to remove, click the vertical three-dot icon (⋮), and click Delete address
  4. Confirm the removal in the modal pop-up

Caution – Once enforced, removing an IP blocks traffic

Once enforcement is activated on the IP allowlist for a given Client ID, removing a CIDR range blocks calls that originate from sources included in it, so that they return a 403 - Forbidden HTTP error.

If you are updating an IP address, ensure you add the new CIDR before removing the old one. If enforcement is activated, you can’t remove the last item from the allowlist.

Mangopay is not responsible for any service disruption resulting from a misconfiguration of the IP allowlist feature.