Skip to main content

Using Rewards with the Connect Widget

The MX Connect Widget is a ready-made user interface that allows developers to quickly add members to Platform and navigate the multi-factor authentication process. It can also be used to manage and resolve connection errors, and it even works with various premium features, such as rewards.

Connecting to an institution in rewards mode will gather rewards information for the member, as well as associated account and transaction data.

This guide assumes you are following MX's recommendation to use the Connect Widget. If your use case requires you to use API endpoints only, see our separate guide on this type of integration.

Prerequisites​

Before you follow the steps in this guide make sure that you have:

  1. Signed up for the Platform API and received your development API Keys.
  2. Integrated the Connect Widget into your application or website. The best way to do this is to use one of the widget SDKs mentioned in Integration Guides that MX has created for this purpose.
  3. Ensure MX has enabled rewards.
Step 1

Create a User​

A user represents your end user in the MX Platform. Make a POST request to the /users endpoint, as shown below.

We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user's name. Don't include any sensitive information here, such as credentials.

info

None of these parameters are required, but the user object cannot be empty. We recommend that partners always set the id parameter when creating a user.

In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can map between your system and ours. You'll need the user guid for nearly every request on the MX API, at least when using basic authorization.

Request
Response
Language:shell

_12
curl -i -X POST 'https://int-api.mx.com/users' \
_12
-u 'client_id:api_key' \
_12
-H 'Accept: application/vnd.mx.api.v1+json' \
_12
-H 'Content-Type: application/json' \
_12
-d '{
_12
"user": {
_12
"email": "test@mx.com",
_12
"id": "My-Test-ID",
_12
"is_disabled": false,
_12
"metadata": "{\\\"type\\\": \\\"individual\\\", \\\"status\\\": \\\"preferred\\\"}"
_12
}
_12
}`

Step 2

Request a Connect Widget URL​

There are many configuration options for the Connect Widget for performing various tasks. Use the following information to configure the Connect Widget for rewards.

Make a POST request to the /users/{user_guid}/widget_urls endpoint.

  • In the path, set the user_guid to the value for the user you created in step 1.
  • In the body:
    • Set the widget_type parameter to connect_widget
    • Set the mode to reward

The response will contain a URL to Connect Widget which you will load in the next step.

Request
Response
Language:shell

_25
curl -L -X POST 'https://int-api.mx.com/users/:user_guid/widget_urls' \
_25
-H 'Content-Type: application/json' \
_25
-H 'Accept: application/vnd.mx.api.v1beta+json' \
_25
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
_25
--data-raw '{
_25
"widget_url": {
_25
"widget_type": "connect_widget",
_25
"client_redirect_url": "https://mx.com",
_25
"color_scheme": "light",
_25
"current_institution_code": "mxbank",
_25
"current_institution_guid": "INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9",
_25
"current_member_guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
_25
"disable_background_agg": false,
_25
"disable_institution_search": false,
_25
"enable_app2app": false,
_25
"include_identity": false,
_25
"include_transactions": true,
_25
"is_mobile_webview": false,
_25
"mode": "reward",
_25
"oauth_referral_source": "BROWSER",
_25
"ui_message_version": 4,
_25
"ui_message_webview_url_scheme": "mx",
_25
"update_credentials": false
_25
}
_25
}'

Step 3

Load the URL and Let the End User Interact​

Load the URL in your application or website. At this point the end user will interact with the Connect Widget. The widget handles the creation of a member as well as the process and any MFA that may be encountered. It automatically asks end users to search for an institution, give their credentials, or authenticate with OAuth. It also deals with any errors along the way.

You'll need to listen for a couple important event messages from the Connect Widget:

  • member status updated which gives you the member GUID and the current connection_status.
  • member connected tells you that the member has been successfully connected and you can move on to the next steps.

Alternatively, if the end user closes the Connect Widget early or some other problem occurs before you see a CONNECTED status, you can use the member_guid to immediately check the member's connection status with a dedicated API endpoint.

Request
Response
Language:shell

_10
curl -L -X GET 'https://int-api.mx.com/users/USR-d60dcf31-e14a-489a-a67a-9476534849c6/members/MBR-fcc99539-8caa-4a7b-8cb6-8b22ae79662e/status' \
_10
-H 'Accept: application/vnd.mx.api.v1beta+json' \
_10
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

info

We suggest you add a Rewards Webhook. Please reachout to MX to have this enabled. We provide webhooks that send HTTPS POST callback requests to the URL of your choice. This webhook notifies you when any new data is available after a successful rewards fetch. For more information on webhooks, see our complete reference page.

Step 4

List Rewards​

Get a list of all rewards data associated with a member by making a GET request to the list rewards endpoint.

The response includes an array of rewards which include account numbers, balance, and type. Make note of the guid as you can use this to read specific rewards using the read Rewards endpoint.

Request
Response
Language:shell

_10
curl -L -X GET 'https://int-api.mx.com/users/USR-d60dcf31-e14a-489a-a67a-9476534849c6/members/MBR-fcc99539-8caa-4a7b-8cb6-8b22ae79662e/rewards' \
_10
-H 'Accept: application/vnd.mx.api.v1beta+json' \
_10
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

Step 5

Read the Account​

Using the account_guid, you can also fetch user account details by making a GET request to the read account.

warning

This endpoint also exists outside of the Rewards product. To include rewards data in the response, you must use the beta accept header: `application/vnd.mx.api.v1beta+json'. If you do not use the correct Accept header, the response will be successful but will not include rewards data.

Notable rewards fields associated with a user's account include:

  • credit_card_product_guid
  • enrolled_in_rewards_on
  • primary_reward_unit
  • current_reward_level
  • next_reward_level
Request
Response
Language:shell

_10
curl -L -X GET 'https://int-api.mx.com/users/USR-d60dcf31-e14a-489a-a67a-9476534849c6/accounts/ACT-481fa472-bb3e-47b5-954d-1cd296261d5d' \
_10
-H 'Accept: application/vnd.mx.api.v1beta+json' \
_10
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

Step 6

Read a Credit Card Product​

If a rewards account is a credit card, the account details return a credit_card_product_guid. Use this guid to read more specific credit card details such as has_cashback_rewards or is_accepting_applications, to help drive next steps for your end users.

Request
Response
Language:shell

_10
curl -L -X GET 'https://int-api.mx.com/credit_card_products/CCA-b5bcd822-6d01-4e23-b8d6-846a225e714a' \
_10
-H 'Accept: application/vnd.mx.api.v1beta+json' \
_10
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'

On this page