Client onboarding

Getting your credentials

Everything you need to go from zero to authenticated. Get your API credentials, set up your environment, and be ready to make your first request.

The path to your first API call

Four steps from landing here to a working integration:

Get credentials

Request your API key and secret

Set up environment

Configure your workspace

Learn auth

Understand HMAC signing

Make first call

Hit the API for real

Step 1: Request your credentials

To access the Mercury API, you need two credentials issued by the Mercury team. These are provided as part of your distributor partnership onboarding.

API Key

Identifies your distributor account. Sent in the x-api-key header on every request. Not secret, but do not share publicly.

Secret Key

Used to generate HMAC-SHA256 signatures. Never transmitted over the wire. Treat like a password. If compromised, contact Mercury immediately to rotate.

Tell us about your integration and the Mercury team will be in touch to set up your sandbox access:

Request API access

The form asks for your company name, use case, and expected transaction volumes. The Mercury team reviews each enquiry and will provision your sandbox credentials once your programme is set up.

What you will receive

Mercury will provide you with two sets of credentials and environment details:

SANDBOXStart here

Sandbox API Key

Sandbox Secret Key

Sandbox base URL

https://www.api.external.test.mercury.global

Mirrors production behaviour. No real money movement. Use for all development and testing.

PRODUCTIONWhen you are ready

Production API Key

Production Secret Key

Production base URL

Provided after integration review

Separate credentials. Same API surface. Only a base URL change needed. Issued when your integration passes review.

Step 2: Set up your environment

Store your credentials securely and configure your development environment. Never hardcode secrets in source code.

# Add to your shell profile (.bashrc, .zshrc) or .env file
export MERCURY_API_KEY="your-sandbox-api-key"
export MERCURY_SECRET_KEY="your-sandbox-secret-key"
export MERCURY_BASE_URL="https://www.api.external.test.mercury.global"

# .env file (add to .gitignore!)
MERCURY_API_KEY=your-sandbox-api-key
MERCURY_SECRET_KEY=your-sandbox-secret-key
MERCURY_BASE_URL=https://www.api.external.test.mercury.global

# In your code
from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.getenv("MERCURY_API_KEY")
SECRET_KEY = os.getenv("MERCURY_SECRET_KEY")
BASE_URL = os.getenv("MERCURY_BASE_URL")

// .env file (add to .gitignore!)
// MERCURY_API_KEY=your-sandbox-api-key
// MERCURY_SECRET_KEY=your-sandbox-secret-key
// MERCURY_BASE_URL=https://www.api.external.test.mercury.global

require("dotenv").config();
const API_KEY = process.env.MERCURY_API_KEY;
const SECRET_KEY = process.env.MERCURY_SECRET_KEY;
const BASE_URL = process.env.MERCURY_BASE_URL;

Keep your Secret Key safe.

Store in environment variables or a secrets manager, never in code
Add .env to your .gitignore immediately
Never log it, print it, or include it in error reports
Use separate credentials for sandbox and production

Verify your setup

Before diving into authentication, confirm your credentials work by calling an unauthenticated lookup endpoint. This verifies network connectivity and that you can reach the Mercury API:

curl -s "https://www.api.external.test.mercury.global/api/v1/lookup/currencies" | head -c 200

{
  "status": "success",
  "data": [
    { "display": "British Pound", "value": "GBP" },
    { "display": "Euro", "value": "EUR" }
  ]
}

If you get a JSON response, you are connected. If you get a timeout or connection error, check your network and firewall settings.

Choose your tooling

Pick the approach that fits your workflow. All three get you to the same place.

cURL + Code

Write signing logic in your language of choice and call the API directly from code or terminal.

Auth guide with code examples

Postman collection

Import our pre-built collection with auto-signing. Explore every endpoint with zero code.

Postman setup guide

Helper tool

Generate auth headers in your browser. Paste into cURL. Great for quick testing and debugging.

Helper tool guide

Sandbox vs production

The sandbox is a full replica of the production environment. Build and test your entire integration here first.

	Sandbox	Production
Base URL	api.external.test.mercury.global	Provided on go-live
Credentials	Separate sandbox key pair	Separate production key pair
API surface	Identical to production	Identical to sandbox
Real money	No	Yes
To switch	Change base URL and credentials. No code changes needed.

Design your integration with the base URL as a configuration variable from the start. This makes the sandbox-to-production switch a one-line change.

Going to production

When your sandbox integration is complete, the Mercury team will review it and issue production credentials. Here is what to expect:

Build in sandbox

Implement your full integration using sandbox credentials. Test all flows: client creation, account provisioning, payments, and webhook handling.

Request production review

Contact the Mercury team when you are ready. They will review your integration and confirm readiness.

Receive production credentials

Mercury issues a separate API key and secret key for production, along with the production base URL.

Switch and go live

Update your environment variables with production credentials and base URL. Your code stays exactly the same.

Quick reference

Auth header	What it carries
x-api-key	Your API Key (identifies your distributor account)
x-nonce	A unique value per request (UUID recommended). Prevents replay attacks.
Authorization	Your HMAC-SHA256 signature, generated using your Secret Key and sent as `HMACSHA256 {signature}`.

Credentials ready? Let's go.

Learn how Mercury's HMAC authentication works, then make your first successful API call.

Authentication Guide First Request Postman Collection