Held Data Best Practices

This document provides a comprehensive overview of the system architecture and its key components. The purpose is to outline the design principles, components, and the interactions between them.

IDs

ID Prefixes

We recommend using prefixes for all IDs to make them easily identifiable. A user ID would start with "U-", a member ID with "M-", an account ID with "A-", and a transaction ID with "T-". This makes it very easy to always know what kind of ID is being used in each place, especially when using MDX Real Time when multiple IDs will be on the URL.

ID Format

IDs appear on the URL in MDX Real Time and MDX On Demand requests. They must be URL-safe. The MDX specification limits them to letters, numbers, and the dash and underscore characters. If the value you need to use as an ID is not URL-safe then we recommend you encode it with hex encoding or url-safe base64-encoding.

If using the base64 option it is recommended that you pad the ID to a multiple of three bytes before converting it to base64 so that there will be no padding characters on it since the padding character is not URL-safe. This avoids the need to do URL percent-encoding on the IDs.

Using User IDs

For a user ID, we recommend that you use a value that already exists in the user's record but not an account number or other sensitive value. If you have a record number or a similar value, that is ideal. Using a value that already exists in the user's record makes it predictable which will facilitate expanding your integration later to include additional APIs.

The ID does need to be URL-safe since it appears on the URL in our API requests. If the value you choose contains non URL-safe characters, you can simply encode using hex-encoding or URL-safe base64 encoding. We recommend prepending "U-" to the front of user IDs to make them easily identifiable.

Using Member IDs

The member ID can be based on the same value as the user ID so you only have a single value to deal with. We recommend that you prefix the member ID with "M-" to make it easily identifiable. For example, If your ID value is "1234", then the user ID would be "U-1234" and the member ID would be "M-1234".

Using Account IDs

Most systems have an account ID that is either globally unique or unique per user. That value can be used as the account ID because in the MX system an account ID need only be unique within the member. The account ID does show up on the URL in MDX On Demand and MDX Real Time requests.

If the account ID value is a sensitive value, either use another value such as a record number, or ensure the value is encrypted or hashed. We recommend prepending "A-" to the account ID to make it easily identifiable.

Using Transaction IDs

Transaction IDs must be unique within the account and consistent from one data feed to the next. If you already have a value available that meets these criteria then you can use it. When possible we recommend prepending "T-" to transaction IDs to make them easily identifiable.

If you need to manufacture a transaction ID, there is a combination of available values. Many systems have a sequence number that is unique per day and a combination of the posted date and the sequence number would be unique within the account.

For example, if the sequence number is six digits then the transaction ID can be similar to this pattern: "T-20150820-123456". Pending transactions that do not have a posted date can use the transaction date or other fields to ensure uniqueness.

If possible it is ideal to use a transaction ID that will not change when a transaction changes from a pending status to a posted status. If this is not possible the MDX specification does allow the ID to change when the transaction status changes.

Data Management

MX is unable to handle requests to perform mass deletes or mass updates of data held on MX's servers. For this reason, it is best practice for you to consider these needs in the initial phases of integrating to MX. MX APIs provide endpoints to perform all create, read, update, and delete actions (CRUD) on data entities in the MX platform.

Consider using all of these endpoints in their integration to keep objects up to date. When using MDX On Demand, the ongoing updating of accounts and transactions data will be handled through the daily On Demand requests. Also consider how to keep User and Member data up to date. Potential needs may include: deleting inactive or canceled users, updating user info, updating member credentials if using login/password, and others.

If these steps are not integrated in the initial phases and you desire to have large sets of data deleted or updated, then plan to do so using a script. Using the MDX Real Time API, create an API script to run through a list of object ids and perform the desired API calls to MX.

Auto-enrollment and Login Workflow

We have provided a recommended workflow for auto-enrolling Users to implement in your login process. We recommend this workflow - even for the all-in approach and for those who are keeping track of Users created. Use of this workflow will eliminate unnecessary API calls; it will also ensure that the User and Member exist and are up-to-date in case anything goes wrong or data gets out of sync between MX and your systems.

Userkeys

When we send an MDX On Demand create session request, we will provide the userkey you assigned to the member when you created it. The userkey is not the same as the member ID which you also assign to the member. The member ID appears on the URL in API requests to identify the member in our system. The userkey is a credential that you will use to validate the user, and it is only used when we send you an MDX On Demand create session request. You can base the userkey on the same value you use for the user ID and member ID or use a different value in your system that will uniquely identify the user. We recommend it be a static value that won't change. The userkey may be as simple as "K-1234" or you may hash it or encrypt it. The userkey can contain any UTF-8 character so it is not limited to URL-safe characters.

Sending First Name, Last Name and Email

Although not required, we recommend sending first name, last name, and email if the data is available. Having this data in the MX system will greatly improve analytics data as well as improve troubleshooting for support issues on specific users.

Handling Closed Accounts

We encourage all data providers to provide account and transaction details for recently-closed accounts (those closed within the past 30 days, for example). This allows us to update these accounts on the MX platform so the user will see the closed status and final zero balance.

In the past, many data providers have not included closed accounts in their data feed. This works well for new users who might not want to see closed accounts when they first open the software, but it does not work well for existing users who already have that account in their MX data.

Example

Consider the case of a car loan. The user opens the loan and makes payments for years in which MX has received as a part of the data feed. When the user makes the final payment, their car loan account is closed. MX did not receive a zero balance or the final transaction for the account because it was no longer included in the data feed so we do not display the account as paid off or closed to the end user.

The best user experience occurs if the data provider includes information on recently-closed accounts. This allows the final zero balance to be provided to MX and, if using the MDX protocol, the is_closed field can be set to true to signal that the account is closed. MX will then automatically mark the account as closed for the user, update the balance to zero, and then request transactions for that account. These final transactions that occurred as the account closed will then complete the user's financial picture for that account.

MX intelligently handles closed accounts received in the data feed. If the user already has that account then we will update it, but we will not add it if the user does not already have it. This allows MX to ignore recently closed accounts for a brand-new user, but to be able to update accounts that close if the user already has them in their data.

Queueing MDX on Demand Requests

We recommend that you build a mechanism into your MDX On Demand service to manage the number of simultaneous requests you can process. This is particularly important if the available connections needed to get the data are limited. The number of requests received in a short period of time may vary due to the number of users logging in. The queueing mechanism will help to smooth out the request load so it can be processed successfully.

MX will wait for up to 60 seconds for the response to an MDX On Demand request. After 60 seconds MX will terminate the request and cancel the job. A queueing mechanism can take advantage of this and allow a delay in responding to the request until you are able to do so.

How the Queueing Mechanism Works

• Set up a queue that can "hold" requests that cannot be executed immediately.
• When a request is received, process it immediately if the request queue is empty and there is a connection available to get the data. If no data connection is available, put the request into the queue, along with the Job Type (see below) and a timestamp of when the request was received.
• Check the MDX-Job-type header of the request being queued. If the job type is foreground, put the request in the queue ahead of requests where the job type is background so that it takes priority.
• When a data connection becomes available, check the queue for pending requests. When present, process the next request in the queue.
• If a request in the queue is approaching the 60-second timeout limit and cannot be processed, return a 429 Too Many Requests error and remove it from the queue. This is preferred to letting the request expire since the 429 error makes it clear that there is a capacity issue, rather than the job simply failing for a lack of response.

info

Foreground jobs are given priority over Background jobs because the user is present during a Foreground job so we need to ensure their data is updated.

We suggest that you make transactions requests a priority. If you are receiving a transactions request after the sessions and accounts requests have already succeeded, it is recommended to reject a sessions request for a new job, or an accounts request for a job that is almost finished.

What to Provide in a Data Field When a Value is Not Available

The best practice is to omit a field from the request when you do not have a value to provide. This avoids any possibility that a field value will be set inadvertently. This is particularly important in an update (PUT) request. If a field is provided with a null value, it may overwrite any existing value on that field. Only provide a field in an update request when you specifically want to set the value of that field.

It is also best to omit empty fields in a create (POST) request. In rare cases where that is not possible, pass the field without a value. An empty set of tags or a self-closing tag can be provided when using XML format, e.g.,<apr></apr> or <apr />. A value of null can be provided when using JSON format, e.g., "apr":null.

Do not provide placeholder values in data fields, e.g., providing a value of 0 in the apr field of an account. The MX system will interpret this as an actual apr value of zero, not as the lack of a value. Similarly, empty strings, e.g., "", must not be provided as the value of a field when using JSON format. Do not provide a value for a field when the correct value is not available.

MX has separate fields for the transaction date (transacted_at, transacted_on) and the posted date (posted_at, posted_on. Provide values for both when the transaction has posted, i.e., when it's status = POSTED. If only one date is available in your system, provide that date as both the transaction date and the posted date. Only provide valid dates; do not use a placeholder or default value such as 1970-01-01. This is important when using MDX On Demand, where the posted date is used for reconciliation purposes.

Storing Data in the Metadata Field

Most objects on the MX platform include a writable metadata field. This field enables you to store additional information related to that object. For example, creating a transaction may send information in the metadata field with its create request.

We recommend you use a key-value format such as JSON for metadata content. This allows you to store any number of key-value pairs. Encode the contents using an encoding such as base64 so the information can be included in either JSON- or XML-formatted responses.

MX will not remove or alter the metadata field. See the FAQ article for information on which party controls the metadata field in each object.

Encoding example

If you want to store two pieces of information in the metadata field, these can be represented by two key-value pairs: rewards_eligible (a boolean field) and reward_program (a string field).

JSON-formatted data: {"rewards_eligible":true,"reward_program":"MILES"}

These data are then encoded using base64.

Base64-encoded JSON data: eyJyZXdhcmRzX2VsaWdpYmxlIjp0cnVlLCJyZXdhcmRfcHJvZ3JhbSI6Ik1JTEVTIn0=

Store the base64 value in the metadata field when they create the transaction. When you read the transaction, decode the base64 value to get the JSON key-value pairs.

This method allows key-value pairs to be added as needed without compromising any existing data.