Mercury Integration Guide

Welcome to Payvy's Mercury Integration Guide! This documentation will help you seamlessly integrate Mercury's API with Payvy to manage your accounts payable and receivable processes efficiently and securely. Follow the steps below to get started.

Getting Started

To begin using Mercury with Payvy, follow these simple steps:

1. Log into Your Mercury Account

   • Navigate to Mercury's website and log in to your account.
   • If you don't have an account, sign up here.

2. Generate an API Key

   • Go to the Settings page in your Mercury dashboard.
   • Click on API Tokens and then Create Token.
   • Select the appropriate Token Type (Read Only, Read and Write, or Custom) based on your needs.
   • Configure the Scopes to limit the token's permissions to only what's necessary.
   • Click Generate and securely store your API token. Important: You won't be able to view it again after closing the dialog.

3. Whitelist IP Addresses

   • To enhance security, whitelist the IP addresses from which you'll access the Mercury API.
   • In the Settings page, navigate to IP Whitelists.
   • Add the IPv4 or IPv6 addresses provided by your hosting platform (e.g., Payvy's server IP).
   • Note: Read Only tokens do not require an IP whitelist.

Securing Your API Token

After generating your API token, it's crucial to secure it to prevent unauthorized access:

• Store Securely: Save your API token in a secure location. Do not expose it in source control or unsecured environments.
• Treat Like a Password: API tokens can access your Mercury account just like a real user. Handle them with the same level of security as passwords.
• Revoke if Compromised: If you suspect that your token has been leaked or stolen, immediately revoke it and generate a new one from your Mercury dashboard.

Token Permission Tiers

Mercury offers three types of API tokens, each with different permission levels:

1. Read Only

   • Permissions: Can fetch all available data on your Mercury account.
   • Use Case: Ideal for applications that need to read data without making any changes.
   • IP Whitelist: Not required.

2. Read and Write

   • Permissions: Can initiate transactions and manage recipients.
   • Use Case: Suitable for applications that need to both read and modify data.
   • IP Whitelist: Required for enhanced security.

3. Custom

   • Permissions: Limited to specific scopes as defined during token creation.
   • Use Case: Best for applications that require granular control over API access.
   • IP Whitelist: Required if scopes include write access.

   Scopes allow you to specify the level of access an API token has. When creating a Custom token, select the fewest scopes needed to perform the required tasks.

   • Note: Scopes cannot be edited after creating a Custom token. If you need different scopes, create a new token with the necessary permissions.

Token Downgrades

To enhance security, Mercury proactively manages API tokens by adjusting their permissions based on usage:

• Permission Adjustment: Tokens with broader permissions than necessary will have their permissions reduced after a 45-day period of usage.
• Token Deletion: Tokens unused for 45 days are automatically deleted.
• Notification: You'll receive an email notification seven days before any token is downgraded or deleted.

IP Whitelists

Whitelisting IP addresses adds an extra layer of security to your API tokens:

• Requirement: IP whitelisting is mandatory for Read and Write tokens and Custom tokens with write scopes.
• Configuration:

  1. Navigate to IP Whitelists: In the Settings page of your Mercury dashboard, go to IP Whitelists.

  2. Add IP Addresses: Enter the IPv4 or IPv6 addresses from which Payvy will access the Mercury API.

  3. Save Changes: Click Save to apply the whitelist.