In order to authenticate their requests to the Mambu Payments API, customers must combine two levels of authentication:

Level

Description

Network

Network-level authentication mechanisms supported are:

IP whitelisting
Mutual TLS (mTLS) authentication
VPN connectivity
AWS PrivateLink

Application

API keys are used for application-level authentication.

ℹ️
Only mTLS is supported (but optional) in sandbox.

1. IP whitelisting and mTLS

1.1. IP whitelisting

Mambu Payments can whitelist a range of IPs to authenticate your API requests against. To register your IPs, please contact support@numeral.io.

1.2. mTLS

If you do not have static IPs or prefer to use mTLS over IP whitelisting, follow the steps below to generate and share a certificate signing request (CSR) with Mambu Payments.

1.2.1. Generate an authentication certificate private key

Generate an authentication private certificate key using the following bash command.

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096

⚠️
Make sure to keep this private_key.pem private key secret. No one but you should access it. Additionally, use a different mTLS certificate for each environment (sandbox and production).

1.2.2. Create a configuration file

Create a configuration file named csr.conf using the following template.

[req]
default_bits = 4096
distinguished_name = dn
prompt = no
req_extensions = req_ext

[dn]
# Required - Fill in your country code using iso-3166-alpha2-code format
C="FR"

# Required - Fill in your company name
O="Company name"

# Optional - Fill in your organization unit name or comment the following line
OU="Organisational unit / department"

# Required - Fill in your email address
emailAddress="email@yourdomain.com"

# Required - Please use one of the following values:
# - sandbox environment: "Numeral sandbox mTLS API"
# - production environment: "Numeral production mTLS API"
CN="Numeral sandbox mTLS API"

[req_ext]
subjectAltName = @alt_names

[alt_names]
# Required - Fill in your domain
DNS.0 = <system/hostname>.yourdomain.com

⚠️
Make sure to replace the above variables with your own values and ensure that the following variables are filled as such:
Variable
Comment
CN
Choose the value depending on the environment:

sandbox: "Numeral sandbox mTLS API"

production: "Numeral production mTLS API"

DNS.0
Your real domain is expected, but you may choose a hostname of your choice and convenience, for instance to distinguish the service and / or the environment calling the Mambu Payments API.

1.2.3. Generate a CSR

Generate an authentication certificate CSR, based on the private key and the configuration file previously created using the following command.

openssl req -new -key private_key.pem -out mtls.csr -config csr.conf

After you have generated your authentication certificate CSR, send it to support@numeral.io. Once signed, we will send you your mtls.crt certificate used to call the API.

1.2.4 Authenticate your API requests with the certificate

Finally, validate your certificate with a request on our API sandbox endpoint using your certificate.

curl -s \
    --key private_key.pem \
    --cert mtls.crt \
    -H 'X-API-KEY: YOUR_API_KEY' \
    https://mtls.sandbox.numeral.io/v1/connected_accounts

⚠️
Do not forget to use the appropriate URL depending on the environment, either sandbox (mtls.sandbox.numeral.io) or production (mtls.api.numeral.io).

If your server receives an HTTP 200 response with the list of connected accounts, it means that the authentication was successful. Otherwise, 2 situations can occur:

An HTTP 403 response with { "message": "Forbidden" } in the body means that the certificate is invalid
If no certificate is provided at all, the TLS handshake will fail with the following response:

1.2.5. Certificate renewal

Mambu Payments supports rolling updates, with old and new certificates accepted during a transition period, to prevent any downtime.

2. API keys

Generate an API key and pass it into the X-API-Key HTTP header of every API request:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/connected_accounts' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'

All API requests must be made over HTTPS with a valid API key. API requests made over plain HTTP will be rejected. API requests sent without a valid API key will be rejected too.

⚠️
Do not share your API key in publicly accessible areas, such as your GitHub repository, in client-side code, or in log management tools.
If your API key gets compromised, you can disable it and create a new one directly from the Mambu Payments dashboard.