Skip to main content
All Platform API requests must use HTTPS with TLS 1.2 or later, or mutual TLS, and must be authenticated.

​
Basic authentication

Most endpoints use basic access authentication with your client_id and api_key. Get these credentials from the Client Dashboard. Set the Authorization header to Basic followed by the Base64 encoding of client_id:api_key:
For example, the Base64 encoding of CLIENT-1234:API-KEY-4567 is Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3, so the header is:
Many HTTP clients encode the credentials for you. For example, curl’s -u client_id:api_key option sends the same header. In v20260929, Data Exchange endpoints also require an MX-3DX-TOKEN header. See the Data Exchange overview.
Keep your client_id and api_key secret. Don’t put them in client-side code, and don’t share them in public repositories or forums. These credentials can grant access to your data.
To avoid revealing private information, some requests that fail authentication return 404 Not Found instead of 401 Unauthorized.

​
Bearer authentication

A few processor endpoints use bearer authentication instead of your client_id and api_key:
  • Request an account number (GET /account/account_numbers)
  • Check real-time account balance (POST /account/check_balance)
  • Read the account balance (GET /payment_account)
  • Get account owner information (GET /account/transactions)
For these endpoints, the processor exchanges an authorization code for an access token, then sends it in the Authorization header:
For the full flow, see the processor guide.

​
Mutual TLS

To use mutual TLS (mutual authentication), securely send MX your PEM-formatted certificate and the name of the trusted certificate authority (CA) that signed it. If your certificate isn’t signed by a trusted CA, you must:
  • Provide the full certificate chain (root, intermediate, and leaf) to MX.
  • Make sure your system trusts the root and intermediate CAs.
To avoid interruptions, send replacement certificates to MX Support at least 30 days before your current certificate expires.

​
IP allowlisting

All requests to MX APIs must come from an IP address on your allowlist, which you configure on the Client Dashboard. Requests from any other IP address return 403 Forbidden. IP addresses outside the United States aren’t normally permitted, so MX reviews requests to add non-US IP addresses before approving them. If MX has questions or needs more information, MX will contact you by email.

​
MX IP address ranges

MX runs multiple data centers for failover and load balancing. Each data center has a range of IP addresses, and any address in these ranges can be active. The DNS entries for MX API URLs can resolve to any IP address in these ranges, and the address can change at any time. If you allowlist the IP addresses that MX API URLs resolve to, you must allowlist every range:

​
DDoS protection

MX provides on-demand distributed denial-of-service (DDoS) protection through Akamai’s DDoS scrubbing center. During a DDoS attack, MX redirects inbound traffic (requests coming into MX) through Akamai. Outbound requests (requests MX sends to you or your partners) still come from the IP ranges above. Outbound requests include, but aren’t limited to, mobile upstream events, webhooks, and aggregation requests. If your firewall rules restrict outbound connections to allowlisted IP addresses, add Akamai’s addresses to avoid a service disruption during DDoS mitigation. To learn which IP addresses Akamai may use during an attack, and to subscribe to updates, see Akamai’s official documentation.

​
Encrypted responses

The Platform API can encrypt responses in JSON Web Encryption (JWE) format. To receive an encrypted response, include these headers in your request: No account configuration is needed. If the headers are present and valid, the API encrypts the response. Decrypt the JWE with your private key to get the original response. If the cipher or public key is invalid, the API returns 412 Precondition Failed with an unencrypted error message: