> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mobile Applications (React Native)
**LEGACY GUIDE**
This guide is for Platform API v2011101. For guidance on the newest version, see [Connectivity Integration Guides](/products/connectivity/overview/connectivity-integration-guides/).
In the following steps, we'll use the [React Native Widget SDK](/other/legacy-connectivity-guides/react-native-legacy-sdk) to embed the Connect Widget into your mobile application. The Connect Widget manages gathering end user's credentials and connecting to end user's accounts to fetch the financial data you need. This guide starts from the beginning and demonstrates how to set up the SDK, configure the connect widget, and read the financial data you need in order to verify information for payments.
The overall flow for Deposit Account Opening is as follows:
1. Download and Setup the SDK
2. Create a user and configure the Connect Widget to use Account Aggregation, Instant Account Verification, and Account Owner Identification.
3. Import the Widget into your application via SDK.
4. Enable the user to interact with the widget.
5. List account and transaction data to learn more about your end user's finances.
6. List account numbers to verify account and routing number for account funding and to identify potential fraud.
7. List account details to verify available balance and the account status for account funding.
8. List account owner details to identify potential fraud.
9. Fetch and list balance data if you plan on moving money or funding accounts after you initially verify the account details.
## 1. Download and Set Up the SDK
Our React Native Widget SDK is available on our [Gitlab](https://github.com/mxenabled/react-native-widget-sdk). You'll first need to download it and follow the React Native Widget SDK Guide to properly embed it in your application. The [React Native Widget SDK](/other/legacy-connectivity-guides/react-native-legacy-sdk) guide instructs you to set up the SDK, but there are still several steps you need to do to ensure the Connect Widget is configured to fetch the data you want for payment verification. If you're not using React Native, review instructions in our [Embedding the Connect Widget in a WebView](/connect/guides/webviews) guide.
## 2. Create a User
A user represents your end user in the MX Platform. Make a request to the [Create User](/api-reference/platform-api/reference/create-user) endpoint (`POST /users`).
We recommend that you include a unique [`id`](/api-reference/platform-api/overview/formats-requirements#identifiers-and-metadata) 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 can't be empty. We recommend that you 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.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"user": {
"id": "partner-2345",
"is_disabled": false,
"email": "example@example.com",
"metadata": "Some metadata"
}
}'
```
```json theme={null}
{
"user": {
"email": "totally.fake.email@notreal.com",
"guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"id": "partner-2345",
"is_disabled": false,
"metadata": "Yada yada yada"
}
}
```
## 3. Configure the Connect Widget by URL or Proxy
When you set up the Widget SDK, you'll need to configure the Connect Widget to fetch the data you want using either a proxy or generating a Widget URL. The following example demonstrates the request for a Widget URL using the Platform API. For more information on using a proxy, review the [Generate a Widget URL](/other/legacy-connectivity-guides/react-native-legacy-sdk) section of our Web Widget SDK guide.
**INFO**
Widget URLs are one-time use. You must fetch a new widget URL each time you load the widget.
In summary, configure the Connect Widget for the following:
* `mode: verification`
* `include_identity: true`
* `include_transactions: true`
Setting the mode to verification fetches account number and routing number.
If your use case requires access to account owner information like name and address, you can use the `include_identity` parameter. This tells the Connect Widget to fetch account owner data after account verification is complete.
If your use case requires account and transaction history, use the `include_transactions` parameter. This ensures that we fetch account details and transaction data at the same time that we fetch account and routing number.
**NOTE**
Setting the `mode` to verification limits the widget search results to institutions that support Instant Account Verification. Setting `include_identity` further limits search results to institutions that support both IAV and account owner identification.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"widget_url": {
"widget_type": "connect_widget",
"color_scheme": "dark",
"mode": "verification",
"include_identity": true
}
}'
```
```json theme={null}
{
"widget_url": {
"type": "connect_widget",
"url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
"user_id": "partner-2345"
}
}
```
## 4. Import the SDK and Render the Widget
Once the steps above have been completed, import components from the `@mxenabled/react-native-widget-sdk` package and render them in your application.
```jsx theme={null}
import React from "react"
import { ConnectWidget } from "@mxenabled/react-native-widget-sdk"
export default function App() {
return (
console.log("Connect Widget Loaded")}
url="https://widgets.moneydesktop.com/md/connect/..."
/>
)
}
```
## 5. Interact with the Connect Widget
The Connect Widget asks end users to search for an institution, provide their credentials, and determine which account they'd like to verify. It may also handle [multifactor authentication](/products/connectivity/overview/mfa) or any errors that occur.
As the end user interacts, you can listen to [postMessage events](/connect/widget-events) by passing callback functions in the widget options object to the class. The option names use the following naming scheme. For example, the `mx/connect/selectInstitution` event is made available via `onSelectInstitution` in the `ConnectWidget` class.
Refer to this [document](https://github.com/mxenabled/web-widget-sdk/blob/master/docs/widget_callback_props.md) for a list of events and their payloads.
| Event | Prop |
| ------ | -------------------- |
| Widget | `on` |
| Entity | `on` |
You'll need to listen for a couple important event messages:
* [member status updated](/connect/widget-events#member-status-update) which gives you the member GUID and the current `connection_status`.
* [member connected](/connect/widget-events#member-connected) tells you that the member has been successfully connected and you can move on to the next steps.
* If you're using `include_identity` (which means using IAV, then an account owner identification), the member connected event message will not trigger until after both processes are complete — that is, after the account owner identification is done.
* Alternatively, if the end user closes the 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](/api-reference/platform-api/reference/read-member-status) via the API.
## 6. Read the Account Data
Get a list of all the account data associated with your user by making a GET request to the [list accounts](/api-reference/platform-api/reference/list-user-accounts) endpoint.
You can see in the following example that the user has 21 accounts associated with it. If you look at the type field, there is a checking account, a savings account, a credit card account, and several others. Also, there is information on the balance of each account, such as APY for credit accounts or payment due days. You won't always get values for every field; that depends on the data provider and the information available from the financial institution in question.
Make a note of the account GUID for the checking account associated with our test member: ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530. We'll need this to list all the transactions associated with the account.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"accounts": [
{
"account_number": "708191771",
"apr": null,
"apy": null,
"available_balance": 1000,
"available_credit": null,
"balance": 1000,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-09-21T19:43:44Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"holdings_value": null,
"id": "act-223434333",
"institution_code": "mxbank",
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"minimum_balance": null,
"minimum_payment": null,
"name": "Checking",
"original_balance": null,
"payment_due_at": null,
"payoff_balance": null,
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "CHECKING",
"updated_at": "2020-09-21T19:52:04Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 21,
"total_pages": 1
}
}
```
## 7. Read Transaction Data
With the account `GUID` you found in the last step, make a request to the [list transaction by account](/api-reference/platform-api/reference/list-transactions-by-account) endpoint. Notice from the pagination object in the response that there are 176 transactions in this account and that the endpoint returned the first 25 of these.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"transactions": [
{
"category": "Gas",
"category_guid": "CAT-b6d63a19-30a7-e852-2703-bdfb4072289e",
"created_at": "2020-09-21T19:43:48Z",
"date": "2020-09-21",
"posted_at": "2020-09-22T12:00:00Z",
"status": "POSTED",
"top_level_category": "Auto & Transport",
"transacted_at": "2020-09-21T12:00:00Z",
"type": "DEBIT",
"updated_at": "2020-09-21T19:43:51Z",
"account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"amount": 7.29,
"check_number_string": null,
"currency_code": "USD",
"description": "ExxonMobil",
"guid": "TRN-822b443e-972c-431e-8dcf-c2b08de21136",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"memo": null,
"merchant_category_code": 0,
"merchant_guid": "MCH-dcd9bbcd-11bb-076a-60c4-90f1101b3372",
"original_description": "ExxonMobil",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 176,
"total_pages": 8
}
}
```
You can access the rest of these transactions by making another request and specifying the number of records you want to access (valid values range between 10 and 100) and specifying the page you'd like to see. You can pass these parameters in the request URL to same endpoint as demonstrated in the following example. The `pagination` object in the response now shows 100 records per page and a current page of 2.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions?records_per_page=100&page=2' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"transactions": [
{
"category": "Paycheck",
"category_guid": "CAT-982ea9e6-3f0e-0c5b-611b-6657a10ba819",
"created_at": "2020-09-21T19:43:48Z",
"date": "2020-07-31",
"posted_at": "2020-08-01T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-07-31T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-09-21T19:43:51Z",
"account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"amount": 23.57,
"check_number_string": null,
"currency_code": "USD",
"description": "Paycheck",
"guid": "TRN-27b176b7-5941-42a4-8085-cfa6657f6dff",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"memo": null,
"merchant_category_code": 0,
"merchant_guid": null,
"original_description": "Payroll",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
},
// •••
],
"pagination": {
"current_page": 2,
"per_page": 100,
"total_entries": 176,
"total_pages": 2
}
}
```
## 8. Read the Account Numbers
By configuring the connect widget to run in `verification` mode and `include_identity`, the Connect Widget can complete IAV and Account Owner Identification after the end user interacts with it. When verification is complete, retrieve account and routing numbers. We have two endpoints for this: [list account numbers by member](/api-reference/platform-api/reference/list-account-numbers-by-member) and [list account numbers by account](/api-reference/platform-api/reference/list-account-numbers-by-account). We show the first here.
* If MX has both an account number and a routing number for at least one of the member's accounts, that information is returned. No information is returned for accounts that are missing a value for one or both of these fields.
* The account number returned from this endpoint may be a Tokenized Account Number (TAN). See the [section on TANs](/products/connectivity/instant-account-verification#tokenized-account-numbers) for information on dealing with these properly.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/account_numbers' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"institution_number": null,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"routing_number": "68899990000000",
"passed_validation": true,
"transit_number": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
```
## 9. Read the Account Details
Before using the account numbers you've just gathered for things like ACH transfers, read the account details by making a GET request to the [read account](/api-reference/platform-api/reference/read-account) endpoint.
Read the account's details to confirm that:
* The `available_balance` shows sufficient funds.
* The account is still open: `is_closed: false`.
This helps [prevent ACH returns](/products/connectivity/overview/best-practices).
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-82a93692-f756-534f-9b2e-ad10a0f38462' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"account": {
"account_number": "****0001",
"apr": null,
"apy": null,
"available_balance": 500000,
"available_credit": null,
"balance": 500000,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-09-21T19:43:44Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": 12,
"death_benefit": null,
"guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"holdings_value": null,
"id": "act-23445745",
"imported_at": "2023-02-24T09:01:25Z",
"institution_code": "mxbank",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"member_id": null,
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "Checking",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": "2021-05-12T16:01:00Z",
"payoff_balance": null,
"premium_amount": null,
"routing_number": "005026788",
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "CHECKING",
"updated_at": "2023-02-24T09:01:25Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
## 10. Read Account Owner Details
After you've connected, list account owner information using the [list account owner](/api-reference/platform-api/reference/list-account-owners-by-member) endpoint to review identity-related data. Information returned depends on what is available from the institution the end user connected to. You'll need the `user_guid` and `member_guid` to pass the request.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/account_owners?page=1&records_per_page=10' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
## 11. Fetch and Read Balance Data for Future or Delayed Payments
Account and routing numbers can be used for things like ACH transfers for as long as the account is still open, so there is no need to use IAV again for the account. However, information about the available balance in that account can become out of date within a few hours.
Before using these numbers again in the future (or if you wait a while to use them after the initial verification) run a balance check to get the latest `available_balance` before you initiate a payment or transfer. This prevents errors related to insufficient funds or closed accounts. For more information on Balance Checks, review our [Balance Check product guide](/products/connectivity/balance-checks).
### a. Fetch Account Balance
Make a POST request to the [check balances](/api-reference/platform-api/reference/list-account-owners-by-member) endpoint.
Aggregating balance data takes some time, so check on the status of this process. Initially, you should see the `is_being_aggregated` field return with `true`.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/check_balance' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2023-02-24T21:33:23Z",
"background_aggregation_is_disabled": false,
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": "Additional information",
"name": "MX Bank",
"successfully_aggregated_at": "2023-02-24T21:11:23Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
### b. Check the Status of the Balance Process
The balance check is complete when the following state is reached. You may need to check the status multiple times using the [read member](/api-reference/platform-api/reference/read-member) endpoint.
* `connection_status: CONNECTED`
* `is_being_aggregated: false`
* `successfully_aggregated_at` updates to the current time.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2023-02-24T21:42:05Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"has_processed_account_numbers": false,
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2023-02-24T21:42:07Z"
}
}
```
### c. Read the Account Details Again
Check to see that `available_balance` is sufficient for your purposes and that `is_closed` is `false`. Make a GET request to the [read account](/api-reference/platform-api/reference/read-account) endpoint.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-82a93692-f756-534f-9b2e-ad10a0f38462' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"account": {
"account_number": "****0001",
"apr": null,
"apy": null,
"available_balance": 500000,
"available_credit": null,
"balance": 500000,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-09-21T19:43:44Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": 12,
"death_benefit": null,
"guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"holdings_value": null,
"id": "act-23445745",
"imported_at": "2023-02-24T09:01:25Z",
"institution_code": "mxbank",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"member_id": null,
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "Checking",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": "2021-05-12T16:01:00Z",
"payoff_balance": null,
"premium_amount": null,
"routing_number": "005026788",
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "CHECKING",
"updated_at": "2023-02-24T09:01:25Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
**INFO**
We suggest you add a Balance Webhook in the Client Dashboard. We provide webhooks that send HTTPS POST callback requests to the URL of your choice. This webhook notifies you when new balance data is successfully returned. Note this webhook does not trigger member-based actions. For more information on webhooks, click [here](/resources/webhooks).