sessions endpoint to authenticate the user. Additional endpoints are used to request account and transaction information once the user is authenticated.
Base URL
The base URL of all MDX On Demand endpoints ishttps://{partner_base_url}/{institution_id}, where {partner_base_url} is your institution’s base URL and institution_id is the ID of the financial institution for which the request is made. This URL varies with each implementation and is provided to MX by you. The base URL may contain a port if needed.
If you’re an online banking provider, we recommend that you use the same value for the client_id and institution_id fields to avoid confusion.
Data Encryption
All API requests must be made over HTTPS. Use only 256-bit SSL encryption or greater. Calls made to your implementation of the API over plain HTTP should fail.Versioning
The MDX version changes as the specification is updated. On Demand requests specify the version that is expected in the response. Data providers may wish to support multiple MDX versions as they upgrade from one version to another. Requests that don’t specify a version should return the latest representation of resources. Unsupported endpoints should return an HTTP status code of 404 Not Found.Headers
All MDX On Demand requests requireAccept, Content-Type, and MDX-Job-Type headers. Refer to Table 1 for the specifics of each.
Table 1. MDX On Demand headers
Sessions
Before you synchronize accounts and transactions with MDX On Demand, you must first obtain a session key. Learn how in Sessions Overview. Once the session is established, you return a session key to MX. MX then provides this session key in anMDX-Session-Key header in all subsequent requests during that session, like this:
Authentication
Every MDX On Demand request requires authentication to ensure secure communication between your institution and MX. Requests must be authenticated via HMAC (Hash-based Message Authentication Code) to verify request authenticity and integrity, and may include IP filtering to validate that requests originate from authorized MX data center IP ranges. In addition to request signing and IP filtering, you may choose to implement any or all of the following: HTTP basic authentication, mutual authentication, and CA certification authentication. Any additional authentication must be set up with MX during your initial integration.HMAC Authentication
HMAC is required for all requests. The process involves calculating an MD5 hash of your request body, building a canonical string from request metadata, and signing that string with your HMAC key. If HMAC orContent-MD5 validation fails, a 412 Precondition Failed error is returned.
Before implementing HMAC, you need:
- An HMAC key (salt): A 32- to 64-byte string encoded in Base64, provided by MX during integration.
- A digest algorithm: Confirm which is configured for your integration: MD5, SHA, SHA1, SHA224, SHA256, SHA384, or SHA512. The most common SHA algorithms are SHA256 and SHA512.
- HTTP headers: You need the ability to set HTTP headers and compute HMAC signatures in your code.
Implementation Steps
To implement HMAC authentication for MDX On Demand, follow these steps:1
Calculate Content-MD5
The
Content-MD5 header verifies request body integrity.For requests with a body, hash the request body using the MD5 hexdigest of the body content.For GET requests without a body, use d41d8cd98f00b204e9800998ecf8427e (MD5 of empty string).Here’s an example of what this looks like in Ruby:2
Build the Canonical String
Construct a canonical string with the following signature pattern:The supported endpoints are:
/sessions/accounts/transactions/user/member/account_owner/account_number
/account_numbers or /account_owners in the canonical string. Using the plural form causes HMAC validation to fail.Here’s an example of a canonical string using a POST request to the /sessions endpoint:3
Generate the HMAC Signature
Sign the canonical string using your HMAC key and the configured digest algorithm. The result must be a lowercase hexadecimal string. Some libraries return uppercase hexadecimal signatures; you can match MX’s lowercase signatures with Here’s an example of what this looks like in Ruby with the SHA1 algorithm:
ToLower() or downcase(), or use case-insensitive comparison.The HMAC key length and signature output length vary by algorithm. For example, SHA1 produces a 40-character signature; other algorithms produce different lengths.
4
Set HTTP Headers
Include the headers in Table 2 in your request.
Table 2. HTTP headers for HMAC authentication
For example:
MX IP Address Ranges
MX maintains multiple data centers for failover and load balancing purposes. Each data center has a range of IP addresses, and any IP address in these ranges can be active. The DNS entries for MX API URLs can resolve to any IP address in our ranges and can change at any time. If you choose to whitelist the IP addresses that the API URLs are allowed to resolve to, you must whitelist all of the IP address ranges. Refer to the following table for a list of these ranges:DDoS Protection
MX provides an on-demand Distributed Denial of Service (DDoS) protection service using Akamai’s DDoS scrubbing center. In the event of a DDoS attack, traffic is only redirected to Akamai. We only redirect inbound requests (requests coming into MX), while outbound requests (requests sent to you or your partners) still come from the existing IP ranges. Outbound requests include, but are not limited to, mobile upstream events, webhooks, and aggregation requests. Although we only redirect inbound requests, if you have firewall rules that prevent outbound connections to whitelisted IP addresses, you must add those to avoid service disruption during a DDoS mitigation event. Visit Akamai’s official documentation to learn more about the IP addresses that may be used in the event of a DDoS attack, and subscribe to this page if you want to be notified when changes occur.HTTP Status Codes
The MDX On Demand API uses conventional HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (for example, a required parameter was missing), and codes in the 5xx range indicate an error with your servers. Refer to Table 3 for a summary of HTTP status codes in MDX On Demand.Table 3. HTTP status codes in MDX On Demand
If you need additional detail to supplement the HTTP status codes, you can use the error messages in Table 4. The code itself is optional, but you must include the
<code> element even if you leave the field blank. The <message> element is required and must include a message.
Table 4. Additional error messages
This is the format for sending an error:
Response Format
The MDX On Demand specification is XML-based. Response formats must adhere to these guidelines:- Responses must be UTF-8 encoded.
- XML tags must be lowercase.
- Reserved XML characters must be properly escaped.
- The XML response must not contain Unicode Byte Order Mark characters (for example,
0xfeff).
Compression
Gzip compression is supported whenContent-Encoding is set to gzip.