> ## 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. # How-to Guide for Clients ## Getting Started This guide is intended for our clients using the MX Platform API. It explains how to move money with a processor by giving them access to user data with an authorization code. This authorization code is then sent to the processor and used by them to request an access token. Before you can begin, MX must enable the Platform API as well as the account verification and payment processing features. You must also ensure you have your `api_key` and `client_id` from the [Client Dashboard](https://dashboard.mx.com). ## Demo App Our demo app provides a concrete implementation of processor tokens and demonstrates how they fit into the MX ecosystem using a simple Ruby on Rails app. Install, run, and review the app's code to see understand more about how the process works. [The demo app is hosted on GitHub.](https://github.com/mxenabled/processor-tokens-client-quickstart) ## Get an Authorization Code The workflow is as follows: 1. Create a user (API call). 2. Connect and verify account numbers (API call and Connect Widget UI). 3. List verified accounts (API call). 4. Identify account owners (optional; multiple API calls). 5. Request the authorization code. 6. If your processor does not require account owner information, you don't need to complete the identity step. A user represents your end user in the MX Platform. Make a request to the [Create User](/api-reference/platform-api/reference/users) 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 Request 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 Response 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" } } ``` Connect a `user` to a financial institution through a `member`. Verifying account numbers always happens through a member, and this verification is required in order to request an authorization code. Use the [Connect Widget](/connect) to create a member and verify it with an MX-provided user interface. You'll need this member's unique GUID for later steps as well. For more information on the Connect Widget, review the guide. Some processors require transaction data and some do not. Configuration of the Connect Widget depends on what data the processor requires. #### A. No Transaction Data Required 1. Make a `POST` request to the get widget URL endpoint with the `user_guid` from step one. 2. Set the `mode` to `verification`. 3. Set the `widget_type` to `connect_widget`. 4. Capture the URL from the response. 5. Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow. 6. Capture the `member_guid` returned in the member connected postMessage during this flow. It will be used in the next step. ```shell Request theme={null} curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "mode": "verification" } }' ``` ```json Response theme={null} { "widget_url": { "type": "connect_widget", "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5", "user_id": "U-jeff-201709221210" } } ``` #### B. Transaction Data is Required If you or your processor's use case requires account and transaction data in addition to account numbers, use the optional `include_transactions` parameter, which fetches the last 90 days of transactions at the same time as verifying account numbers. You also need to know whether the use case requires transaction data only once or continuously. This is determined with the `disable_background_agg` parameter. **For One-Time Transaction Data** 1. Make a `POST` request to the get widget URL endpoint with the `user_guid` from step one. 2. Set the `mode` to `verification`. 3. Set the `widget_type` to `connect_widget`. 4. Set `include_transactions` to `true`. 5. Set `disable_background_agg` to `true`. 6. Capture the URL for an embeddable version of the Connect Widget from the response. 7. Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow. 8. Capture the `member_guid` returned in the member connected postMessage during this flow. It will be used in the next step. ```shell Request theme={null} curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "mode": "verification", "include_transactions": true, "disable_background_agg": true } }' ``` ```json Response theme={null} { "widget_url": { "type": "connect_widget", "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5", "user_id": "U-jeff-201709221210" } } ``` **For Continuous Transaction Data (aggregated daily)** 1. Make a `POST` request to the get widget URL endpoint with the `user_guid` from step one. 2. Set the `mode` to `verification`. 3. Set the `widget_type` to `connect_widget`. 4. Set `include_transactions` to `true`. 5. Set `disable_background_agg` to `false`. 6. Capture the URL for an embeddable version of the Connect Widget from the response. 7. Load the Connect Widget URL. The end user will select an institution and proceed through the Connect Widget flow. 8. Capture the `member_guid` returned in the member connected postMessage during this flow. It will be used in the next step. ```shell Request theme={null} curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "mode": "verification", "include_transactions": true, "disable_background_agg": false } }' ``` ```json Response theme={null} { "widget_url": { "type": "connect_widget", "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5", "user_id": "U-jeff-201709221210" } } ``` After you create and verify a member with the Connect Widget, make a request to the list accounts numbers by member endpoint to retrieve the account numbers tied to that `member`. This request requires the `member_guid` delivered with the Connect Widget's member connected postMessage in the previous step. Capture the `account_guid` returned in this response to use later. ```shell Request 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 Response 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 } } ``` If a processor needs account owner information, complete the identification process before you request an authorization code. This enables processors to request account owner information using their token. It is important that you complete this process only after you've completed the steps outlined above. For more information on identity or account owner information, visit our Account Owner Identification guide. Identifying account owner information is itself a multi-step process which can potentially involve multi-factor authentication and can't be completed with the Connect Widget. You must begin it by making a POST request to the identify member endpoint with the `user_guid` and `member_guid` you captured in previous steps, which is shown in the example below. ```shell Request theme={null} curl -i -X POST 'https://int-api.mx.com/users/USR-fa7537f3-48aa-a683-a02a-b18940482f54/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/identify' \ -H 'Accept: application/vnd.mx.api.v1+json' \ -H 'Content-Type: application/json' \ -u 'client_id:api_key' ``` ```json Response theme={null} { "member": { "aggregated_at": "2016-10-13T18:07:57.000Z", "connection_status": "CONNECTED", "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b", "id": "unique_id", "institution_code": "chase", "is_being_aggregated": false, "is_managed_by_user": false, "is_oauth": false, "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"", "name": "Chase Bank", "oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2", "successfully_aggregated_at": "2016-10-13T17:57:38.000Z", "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54", "user_id": "user123" } } ``` You're now ready to request an authorization code with the following steps: Make a `POST` request to the `/authorization_code` endpoint. In the body of the request, you must include the `user_guid`, `member_guid`, and `account_guid` captured in previous steps. You'll receive an authorization code in the response. **INFO** Authorization codes are one-time use. ```shell Request theme={null} curl -i -X POST 'https://int-api.mx.com/authorization_code' \ -H 'Accept: application/vnd.mx.api.v1+json' \ -H 'Content-Type: application/json' \ -u 'client_id:api_key' \ -d '{ "authorization_code": { "scope": "user-guid:USR-101ad774-288b-44ed-ad16-da87d522ea20 member-guid:MBR-54feffb9-8474-47bd-8442-de003910113a account-guid:ACT-32a64160-582a-4f00-ab34-5f49cc35ed35 read-protected" } }' ``` ```json Response theme={null} { "authorization_code": { "code": "9nN-9D8_4Z3WYazx7-zXfmqsD3jwgL_2W927Sb3otI" } } ``` ## Next Steps You've completed your part of the process. Send the authorization code to your payment processor. They'll need to review the steps in the How-to Guide for Processors.