Skip to content

Latest commit

 

History

History
106 lines (70 loc) · 14.1 KB

README.md

File metadata and controls

106 lines (70 loc) · 14.1 KB
Raw

Plaid Postman Collections

Welcome to the Postman Collections Quickstart Guide! If you're looking for a quick and easy way to get started with the Plaid API with no additional code, this is the place for you.

For the Plaid Quickstart guide that uses code, see the Plaid Quickstart.

Table of contents

Getting started

Don't feel like reading? Want your information in video format instead? Check out our Plaid and Postman in Three Minutes video tutorial.

Follow these steps to quickly get started with the Plaid API:

  1. Sign up with Plaid to get a set of API keys that are required for interacting with the API.
  2. Click the "Run in Postman" button below, and then click the "Fork Collection" button when prompted. You will be required to create a free account with Postman.

Run in Postman

  1. Once both the collection and the environment variables are imported into Postman, see the Configuration section on how to correctly configure API keys with the collection.

Configuration

The Plaid Postman collection uses Postman environment variables to simplify each API request.

plaid-postman-configuration

  1. Select the Sandbox environment in the top right corner
  2. Click the eye icon to open the environment settings
  3. Copy in your Plaid API keys from your Plaid Dashboard, into each field:
  • client_id
  • secret
  1. Save your changes and start making Plaid API requests!

Making API calls in Sandbox

Once you have completed the steps in the Configuration section above, you are ready to make API requests using Postman! The following steps are a quick walkthrough to making an API request. In this example, we will use the special capabilities of the Sandbox test environment to bypass the client-side Link UI and make all of our requests via the backend.

  1. Make sure the "Collection" pane is selected, then expand the "Plaid API Endpoints" folder on the left and navigate to Plaid API Endpoints -> Items -> Item Creation -> Create Item [Sandbox Only].
  2. In the pane on the right, which has the options "Params", "Authorization", "Headers" etc. click on the "Body" tab.
  3. (Optional) If you want, update the product under initial_products to match the product you would like to try, such as "transactions" or "identity".
  4. Click the blue "Send" button on the right.
  5. The response body should appear in Postman. The public_token returned will automatically be used in our next request.
  6. Select the "Exchange token" endpoint, click on the "Body" tab, then hit "Send". An access_token will be returned and will automatically be used in our next request.
  7. Select any product endpoint of your choice. If you are not sure which one to use, a good simple example is "Balance". Expand the product endpoint folder and click on the endpoint you would like to use ("Retrieve Balance", if you are using balance).
  8. Click on the "Body" tab. Complete any other required fields (for Balance, there are none) and click "Send".
  9. You will receive a response containing your requested data!

Income notes

Testing the Payroll Income or Document Income flows requires modifying the steps above. Instead of calling "Create Item [Sandbox Only]", go to the Income folder and call "Create User Token", followed by "Initialize User Token for Payroll Income [Sandbox only]", or "Initialize User Token for Bank Income [Sandbox only]" as appropriate, and then finally "Retrieve Payroll Income" or "Retrieve Bank Income".

Transfer notes

To call Transfer endpoints, you will need either a payment profile token, or both an access token and an account id.

The easiest method is to use an access token an account id. To obtain an access token and account id, follow the Making API calls in Sandbox steps above, then call Items -> Item Management -> Retrieve an Item's accounts.

Once you have the access token / account id pair, start by calling Transfer -> Authorize a transfer, then call Transfer -> Initiate a transfer. Note that you will need to update the request bodies for these endpoints to use only the account identifying mechanism you are choosing -- for example, if you are using the account id and access token approach, delete the payment_profile field before making the request.

If you want to use the Payment Profile approach instead of using an access token and account id, create the Payment Profile by calling Transfer -> Create Payment Profile. If you are using this approach, you will not be able to complete the entire flow in Postman without using Link; after creating the payment profile token, you will need to activate the token by completing a Link session as described in Making API calls with real data in Production or Development. You will only need to complete the process through step 12; it is not required to exchange the public_token. At step 6, where you call /link/token/create in Postman, you will need to add your payment profile token to the /link/token/create request body, by adding the following to the request body: transfer: {payment_profile_token: your_payment_profile_token_goes_here}. (Replace your_payment_profile_token_goes_here with the actual payment profile token returned by calling Create Payment Profile.) If you are not comfortable modifying request bodies in Postman, it is recommended to use the access token / account id approach instead. If using Payment Profiles, make sure to delete the account_id and access_token fields from the request bodies when calling Transfer -> Authorize a transfer or Transfer -> Initiate a transfer.

Identity Verification and Monitor notes

New Plaid customers are not enabled for Identity Verification or Monitor in the Sandbox by default. Submit an Access Request or contact Sales to use the Postman collection.

Identity Verification and Monitor cannot be tested using the instructions above. To test Identity Verification or Monitor, use the instructions below for making Postman calls with real data; but you may optionally use Sandbox instead of Production (Identity Verification and Monitor cannot be used in Development).

In order to call /link/token/create in step 6 below when using Identity Verification, use the "Plaid API Endpoints -> Link Tokens -> Create Link Token (Identity Verification)" endpoint. You will need to provide a template_id in the identity_verification object. This id can be obtained from the Dashboard -- in the upper-left corner, select Identity Verification and Monitor from the team selection drop-down list (if this does not exist, make sure to submit a product access request). Under Identity Verification, click the Integration button, and copy the template_id.

You do not need to complete steps 13-15 below, as a public token is not needed for Identity Verification or Monitor; instead, you can view the status of the verification within the Dashboard.

Making API calls with real data in Production or Development

For reasons of security and transparency, getting an access token for use with real data cannot be done entirely via Postman API calls -- you are required to use the Plaid Link UI component to obtain a public_token, which you can then feed back into Postman. You can do this as follows:

  1. Download the link.html file included in this repo and open it in a text editor (alternatively, open a text editor, create a new file called link.html, and copy and paste the contents of link.html into it). You will use this file later.
  2. Re-visit the "Configuration" steps at the top of this page, but after opening the environment settings, click the "..." button in the upper right and select "Duplicate". This will create a new environment called "Sandbox copy" -- to rename it, click the pencil icon next to the name and name it either "Development" or "Production" as appropriate.
  3. On your newly created environment, change the client_id and secret_key environment variables to your client ID and secret for Production (or Development) instead of for Sandbox, then set the env_url environment variable to production.plaid.com (for Production) or development.plaid.com (for Development).
  4. To apply these new settings, select your new environment from the drop-down in the upper right. Alternatively, while editing the new environment, you can click "..." and select "Set as active environment".
  5. Navigate to Plaid API Endpoints -> Link Tokens -> Create Link Token and click on the "Body" tab.
  6. If you want, replace "auth" with the name of the product you would like to try, such as "transactions" or "identity". Note that only institutions that support ALL the products you specify here will appear in Link -- if you don't see the institution you want when Link is launched, make sure you have listed the right product. For example, an institution that only supports credit cards (e.g. American Express) will not appear in Link if a product that doesn't support credit cards (like auth) is specified.
  7. Click the blue "Send" button.
  8. Copy the value of the link_token from the response.
  9. Return to your local copy of link.html. Replace the text 'your-link-token-goes-here' in link.html with the value you copied in the previous step, and save the file.
  10. Open link.html in a web browser.
  11. Open the web browser Developer Tools (for example, in Chrome, go to View->Developer->Developer Tools), then open the Console tab within Developer tools.
  12. Click the "Link Account" button on link.html to launch Link. The Plaid Link component should launch. Follow the prompts and log into a financial institution. Make sure to use a real username and password, not the Sandbox credentials.
  13. Once the prompts have completed and you have successfully logged in via Link, the Console tab should contain text saying "the public token is:" followed by the value of the public token. Copy the public token value.
  14. Return to Postman and go to API Endpoints -> Item Creation -> Exchange Token, click on the Body tab, and select the public token value -- by default, it is {{public_token}}. Replace this value with your copied public token from the previous step, making sure the token value is inside the quotation marks, then hit Send.
  15. The response will contain an access_token suitable for making calls in Production (or Development)! As in the Making API calls in Sandbox directions, it will be automatically saved for you to use in future requests. You can then follow the same steps as you did in the that section (starting with step 7) to make API requests for real data.

Webhook testing tools

Webhook Tester and Request Bin are useful tools for receiving webhook calls. You can use them to generate a webhook url and use that url for any Postman requests that require you to specify a webhook url, then use the sites to inspect the content of any webhooks they received.