Mercury Getting Started: Account Setup & First API Request

Getting started overview

Getting started with Mercury involves establishing a business account, configuring API access, and executing an initial request to confirm connectivity. Mercury is designed for startups and small businesses seeking streamlined banking operations, offering programmatic access to financial data and transactions through its API Mercury API documentation. This guide outlines the steps from account creation to a successful first API call.

The process typically includes:

1. Signing up for a Mercury business account.
2. Completing the identity verification and business onboarding process.
3. Generating API keys within the Mercury dashboard.
4. Making a test API call to retrieve account information.

Before proceeding, ensure your business meets Mercury's eligibility requirements, which generally include being a US-based company with a federal EIN Mercury eligibility criteria.

Quick reference table

Create an account and get keys

To begin using Mercury, you must first establish a business account. The signup process involves providing details about your business and its owners, followed by a verification process. Once your account is approved and active, you can access the developer settings to generate API credentials.

Account signup process

1. Navigate to Mercury's Website: Go to the official Mercury homepage.
2. Start Application: Click on the "Get Started" or "Open an Account" button.
3. Provide Business Information: You will be prompted to enter details such as your company's legal name, EIN, business address, and industry.
4. Owner Information: Provide personal details for all beneficial owners and key personnel, typically including name, address, date of birth, and Social Security Number. This is required for Know Your Customer (KYC) and Anti-Money Laundering (AML) compliance FinCEN's Beneficial Ownership Rule.
5. Document Uploads: You may need to upload supporting documents like formation documents, operating agreements, and government-issued IDs.
6. Review and Submit: Review all entered information for accuracy and submit your application.
7. Verification: Mercury's team will review your application. This process can take a few business days. You will receive email notifications regarding your application status.

Upon approval, you will gain access to your Mercury dashboard.

Generating API keys

API keys are essential for authenticating your requests to the Mercury API. Mercury uses an OAuth 2.0 client credentials flow for server-to-server communication OAuth 2.0 specification. To generate your keys:

1. Log In: Access your approved Mercury business account dashboard.
2. Navigate to Developer Settings: Look for a section labeled "Settings," "Developer," or "API Access." The exact path may vary but is typically under your profile or company settings.
3. Create New API Key: Within the developer settings, you should find an option to create a new API key pair. This will typically generate a client_id and a client_secret.
4. Secure Your Keys: The client_secret is sensitive and should be treated like a password. Mercury will usually display it only once upon generation. Copy and store it securely. Do not embed it directly in client-side code or public repositories.
5. Define Scopes (Optional): Depending on Mercury's API design, you might be prompted to define scopes or permissions for your API key, limiting what actions it can perform (e.g., read-only access, transaction initiation). Select the necessary permissions for your integration.

These keys will be used to obtain an access token, which then authenticates your API calls.

Your first request

After obtaining your API keys, the next step is to make an authenticated request to the Mercury API. This typically involves two main steps: obtaining an OAuth 2.0 access token and then using that token to call an endpoint, such as retrieving account information.

Obtaining an access token

Mercury's API uses OAuth 2.0 Client Credentials flow. You'll exchange your client_id and client_secret for an access token. This token has a limited lifespan and will need to be refreshed periodically.

curl -X POST \
  https://api.mercury.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

A successful response will return a JSON object containing your access_token and its expires_in duration (in seconds).

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store the access_token securely for subsequent API calls.

Making a test API call

Once you have an access token, you can make your first authenticated request. A common first endpoint to test is one that retrieves a list of your accounts.

curl -X GET \
  https://api.mercury.com/api/v1/accounts \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Replace YOUR_ACCESS_TOKEN with the token obtained in the previous step.

A successful response will return a JSON array of your Mercury accounts, similar to this structure:

[
  {
    "id": "acc_123abcDEF456ghiJKL789mnoPQR",
    "account_number": "XXXXXXXXX",
    "routing_number": "XXXXXXXXX",
    "account_type": "checking",
    "currency": "USD",
    "balance": {
      "available": {
        "amount": "12345.67",
        "currency": "USD"
      },
      "current": {
        "amount": "12345.67",
        "currency": "USD"
      }
    },
    "name": "Main Checking Account"
  }
]

If you receive a response with your account details, your API setup is successful.

Common next steps

With your initial API connection established, you can explore more advanced Mercury API functionalities to integrate banking operations into your applications. Developers often focus on these areas:

• Transaction History: Retrieve detailed transaction data for reconciliation and reporting. The Mercury Transactions API typically allows filtering by date range, account, and transaction type.
• Initiating Payments: Programmatically send funds via ACH or wire transfers. This requires careful handling of permissions and security protocols Mercury Payments API.
• Webhooks: Set up webhooks to receive real-time notifications for events such as incoming transactions, payment status updates, or account balance changes. This eliminates the need for constant polling Mercury Webhooks guide.
• Managing Cards: Integrate with card management features, if available, to issue virtual cards or manage physical card settings.
• Treasury Management: For larger balances, explore API access to Mercury's treasury management features for optimizing interest earnings.
• Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, invalid requests, or service unavailability.

Refer to the comprehensive Mercury API documentation for specific endpoint details, request/response schemas, and example code pertinent to each feature.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are troubleshooting steps for frequent problems:

• 401 Unauthorized:
  • Invalid Access Token: Ensure your access_token is correct and has not expired. Re-obtain a fresh token if necessary.
  • Missing Bearer Prefix: Verify that the Authorization header is formatted as Bearer YOUR_ACCESS_TOKEN, including the "Bearer" keyword and a space.
  • Incorrect Scopes: Confirm that the API key used has the necessary permissions (scopes) for the endpoint you are trying to access.
• 403 Forbidden:
  • Insufficient Permissions: Your API key might not have the required permissions for the specific action or resource. Check your key's scopes in the Mercury dashboard.
  • Account Restrictions: Some actions might be restricted based on your account status or compliance requirements.
• 400 Bad Request:
  • Malformed JSON: Review your request body for syntax errors (e.g., missing commas, unclosed braces).
  • Missing Required Parameters: Ensure all mandatory parameters for the endpoint are included in your request. Consult the Mercury API reference for required fields.
  • Invalid Parameter Values: Check if the data types or formats of your parameters match the API's expectations (e.g., expecting a number but receiving a string).
• 404 Not Found:
  • Incorrect Endpoint URL: Double-check the API endpoint URL for typos.
  • Resource Not Found: If you are requesting a specific resource (e.g., a transaction by ID), ensure the ID is correct and the resource exists.
• Network Issues:
  • Verify your internet connection.
  • Ensure no firewalls or proxies are blocking your outbound requests to api.mercury.com.
• Rate Limiting (429 Too Many Requests):
  • If you receive a 429 status code, you have exceeded the API's rate limits. Implement exponential backoff or wait before retrying your request.

For persistent issues, consult the official Mercury API documentation or contact Mercury's support team for assistance.