What is Helios?

Helios is MX’s group of APIs for implementing mobile app features. Data providers implement the API endpoints for the features they wish to incorporate into their mobile app.

Available APIs

  • Accounts provides a way for MX to read all of a user’s accounts and latest transactions.
  • ACH Transfers provide a way for MX to transfer money between institutions on behalf of a user.
  • Authorization allows you to provide explicit permission for certain high-risk operations, or operations that require further authentication information such as high-volume transactions, live chat, or opening a web view.
  • Challenges is a structure to allow partners to ask questions of the user in certain situations.
  • Click Switch is specifically focused on implementing the clickSWITCH API to make this system available to various customers.
  • Credit Reports is a structure to convey credit report information about the user.
  • Cross-account Transfers provides a way for MX to transfer money between the accounts of different users within a single institution.
  • Documents provides a way for users to view their account statements, tax forms, notices, credit card statements, and other forms of electronic documents related to their accounts.
  • Entitlements are a component of network communications that allow real-time access to features.
  • Identity (ID) provides a way for MX to authenticate the identity of a user using their online banking credentials (i.e., login and password).
  • Locations (branch locator) provides a way for MX to locate a financial institution’s (FI) branches.
  • Managed Cards provides a way for users to view and control their credit and/or debt cards.
  • Origination provides a way for partners to accommodate completely new customers who are creating new accounts with the partner’s institution.
  • Payments (bill pay) is a specification that allows implementers to connect the Helios application to payment providers (typically for bill payments).
  • Payout (person-to-person transfers) allows for external and internal mobile transfers. This API would be used to implement Person to Person payments.
  • Profile provides a way for MX to access and manage all of a user’s profile information.
  • Remote Deposits (RDC) provides a way for MX to remotely deposit money into an account on behalf of a user using a check image.
  • Transfers provides a way for MX to transfer money between accounts within a single institution on behalf of a user.

Security

Requests to our APIs are authenticated with an HMAC. The HMAC is calculated using a secret key that you provide to MX. Requests may also be authenticated with HTTP basic authentication or mutual authentication if your security policy requires.

All API requests will be made from a whitelisted IP address. Calls made from non-whitelisted IP addresses will fail with 403 (Forbidden).

All API requests will be made over HTTPS. Calls made over plain HTTP will fail with 403 (Forbidden).

Versioning

Because our APIs are implemented by you, the specification (spec) is intended to be stable. When backwards-incompatible changes are made, we will publish a new spec with a different version.

Versions are passed as part of the request’s Accept header:

All API requests will specify the API version via the Accept header. Calls that don’t specify a version or that specify a version different from what is currently implemented will fail with 406 (Not Acceptable).

Dates and Times

Dates can be represented in individual objects in two forms: ISO 8601 or Unix Time.

ISO 8601

String-based datetime fields that end with _on use ISO 8601 format. See Calendar Dates for more information.

Examples

1
2
3

"1970-01-01"                - January 1st 1970 @ @12:00pm GMT
"1969-07-21T02:56:15Z"      - July 21st 1969 @ 2:56am (+15 seconds) GMT
"1972-11-07T14:13:00-07:00" - November 7th 1972 @ 2:13pm MST

Unix Time

Number-based datetime fields that end with _at use Unix time format. Unix time is always in UTC. See Unix time and Coordinated Universal Time for more information.

Examples

1
2
3

43200     - January 1st 1970 @ @12:00pm UTC
-14159025 - July 21st 1969 @ 2:56am (+15 seconds) UTC
90018780  - November 7th 1972 @ 2:13pm UTC

Errors

For instances when returning an HTTP response code isn’t specific enough, endpoints may respond with an error.

Error Fields

Name Type Description
error_title String This is the title of error message to display to the user. A generic title will appear if error_title is not included.
user_message String This is the error message to display to the user.
message String This is the error message. Primarily this is a debug field, but will be shown to the user if user_message is not included.
error_code String This is a debug field. This field will not be shown to the user, but may aid in resolving issues.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Status: 422 Unprocessable Entity
Content-Type: application/vnd.mx.mdx.v6+json

{
  "error": {
    "message": "Data mismatch. Required data fields are missing (5003)",
    "user_message": "Some information is missing, please check the fields and try again. If this problem persists please call us at 555-867-5309."
  }
}

Status: 401 Unauthorized
Content-Type: application/vnd.mx.mdx.v6+json

{
  "error": {
    "error_title": "Not authorized",
    "message": "User is not set up to execute this action",
    "user_message": "Unable to perform action, please try again later. If this problem persists please call us at 555-867-5309.",
    "error_code": "az-5003"
  }
}

Warnings

Any POST or PUT request that succeeds and responds with a non-collection response may also include in the response body a field warnings whose corresponding value is an array of warning objects. A warning object contains a single field user_message.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Status: 200 OK
Content-Type: application/vnd.mx.mdx.v6+json

{
  "resource_type": {
    "foo": 123,
    "bar": "baz",
    "warnings": [
      {
        "user_message": "Warning One"
      },
      {
        "user_message": "Warning Two"
      }
    ]
  }
}

HTTP Status Codes

Our APIs use conventional HTTP response codes to indicate 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 (e.g., a required parameter was missing, etc.), and codes in the 5xx range indicate an error with the Data Provider’s servers.

HTTP Status Code Description
200 OK Valid credentials were provided.
202 Accepted Valid credentials were provided, but challenges were returned.
400 Bad Request Often missing a required parameter.
401 Unauthorized The HMAC or provided credentials were invalid.
403 Forbidden The IP address isn’t whitelisted.
404 Not Found The requested item doesn’t exist.
406 Not Acceptable The request didn’t specify a valid API version.
422 Unprocessable Entity The request is valid, but the data is not.
500, 502, 504 Server errors Indicates an error with the Data Provider’s servers.
503 Service Unavailable The service is down for maintenance.

Check the System Status

Checks if an API is online. When the API is online, it returns a 204 (No Content). When the API is offline, it returns a 503 (Service Unavailable). It may return other errors if security requirements aren’t met or if the API is experiencing other problems.

Endpoint:

GET /status

Online Response

1

Status: 204 No Content

Offline Response

1

Status: 503 Service Unavailable