Example requests

Complete request and response examples for three core API operations. Copy, run, and see exactly what comes back.

These examples use pre-computed headers for clarity. In your integration, generate signatures programmatically using the process in the Authentication Guide, or use the Helper Tool to generate headers for testing.

GET

List clients

Retrieve all clients

POST

Onboard a client

Create a new client

POST

Submit a payment

Send GBP via Faster Payments

Example 1: List all clients

The simplest authenticated call. No request body, no path parameters. Perfect for verifying your auth setup works.

GET/api/v1/client

curl -X GET "https://www.api.external.test.mercury.global/api/v1/client" \
  -H "x-api-key: a9F3kL2PqX7WmT8R4N0Bv6HcYzJdE5u" \
  -H "x-nonce: 729522b9-88f9-47df-a102-cd8e53e30a5e" \
  -H "Authorization: HMACSHA256 Tr5YQmM7GD7gFZh8cB2kXfFZ3pB/tuHHkAPlg2zMrpc=" \
  -H "Content-Type: application/json"

[
  {
    "ClientType": "Corporate",
    "Identifier": "CLIENT-001",
    "ExternalReference": "EXT-REF-001",
    "ExpectedMonthlySpend": 5000,
    "RiskRating": "Low",
    "Contacts": [
      {
        "Identifier": "b7809e48-6407-4b44-b613-921049f2d7e8",
        "FirstName": "Jane",
        "LastName": "Smith",
        "PhysicalAddress": {
          "Street": "1 High Street",
          "City": "London",
          "Region": "Greater London",
          "Postcode": "EC1A 1BB",
          "CountryCode": "GB"
        },
        "DateOfBirth": "1985-06-15"
      }
    ],
    "CorporateDetails": {
      "Name": "Acme Ltd",
      "RegistrationNumber": "12345678",
      "RegisteredAddress": {
        "Street": "1 High Street",
        "City": "London",
        "Region": "Greater London",
        "Postcode": "EC1A 1BB",
        "CountryCode": "GB"
      },
      "IndustryCode": "6419"
    }
  }
]

Auth typeHMAC-SHA256 (3 headers)

Body in signatureEmpty string (GET request)

ReturnsArray of client objects

Example 2: Onboard a new client

Creates a new client under your distributor account. The request body is part of the string to sign and must be byte-for-byte identical to what you send.

POST/api/v1/client

curl -X POST "https://www.api.external.test.mercury.global/api/v1/client" \
  -H "x-api-key: a9F3kL2PqX7WmT8R4N0Bv6HcYzJdE5u" \
  -H "x-nonce: c4a81d70-22bf-4f12-9e3a-8b5c6d7e8f90" \
  -H "Authorization: HMACSHA256 kJ9mNpQ2rS4tU6vW8xY0zA1bC3dE5fG7hI9jK1lM3n=" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "EXT-REF-001",
    "clientType": "Corporate",
    "riskRating": "Low",
    "expectedMonthlySpend": 5000,
    "associates": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "dateOfBirth": {
          "year": 1985,
          "month": 6,
          "day": 15
        },
        "physicalAddress": {
          "street": "1 High Street",
          "city": "London",
          "region": "Greater London",
          "postcode": "EC1A 1BB",
          "countryCode": "GB"
        }
      }
    ],
    "corporate": {
      "name": "Acme Ltd",
      "registrationNumber": "12345678",
      "registeredAddress": {
        "street": "1 High Street",
        "city": "London",
        "region": "Greater London",
        "postcode": "EC1A 1BB",
        "countryCode": "GB"
      },
      "industryCode": "6419"
    }
  }'

{
  "Response": {
    "ClientType": "Corporate",
    "Identifier": "CLIENT-001",
    "ExternalReference": "EXT-REF-001",
    "ExpectedMonthlySpend": 5000,
    "RiskRating": "Low",
    "Contacts": [
      {
        "Identifier": "b7809e48-6407-4b44-b613-921049f2d7e8",
        "FirstName": "Jane",
        "LastName": "Smith",
        "PhysicalAddress": {
          "Street": "1 High Street",
          "City": "London",
          "Region": "Greater London",
          "Postcode": "EC1A 1BB",
          "CountryCode": "GB"
        },
        "DateOfBirth": "1985-06-15"
      }
    ],
    "CorporateDetails": {
      "Name": "Acme Ltd",
      "RegistrationNumber": "12345678",
      "RegisteredAddress": {
        "Street": "1 High Street",
        "City": "London",
        "Region": "Greater London",
        "Postcode": "EC1A 1BB",
        "CountryCode": "GB"
      },
      "IndustryCode": "6419"
    }
  }
}

Signing POST requests: The JSON body you include in your signature must be the exact string you send in the request. If your HTTP library re-serialises the JSON (changing key order or whitespace), the signature will not match. Use data= in Python, not json=.

Body in signatureFull JSON request body

Key field returnedIdentifier (use for subsequent calls)

Required fieldsreference, type, risk, spend, associate, corporate

Example 3: Submit a GBP payment

Sends money via Faster Payments. Requires an active client with a funded GBP virtual account. The payment is asynchronous: you receive a Pending status immediately, then track settlement via webhooks.

POST/api/v1/payments

curl -X POST "https://www.api.external.test.mercury.global/api/v1/payments" \
  -H "x-api-key: a9F3kL2PqX7WmT8R4N0Bv6HcYzJdE5u" \
  -H "x-nonce: e5b92c81-33cf-4a23-bf4b-9c6d7e8f01a2" \
  -H "Authorization: HMACSHA256 pR3sT5uV7wX9yZ0aB2cD4eF6gH8iJ1kL3mN5oP7qR=" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CLIENT-001",
    "endToEndIdentifier": "PAY-2026-04-13-001",
    "debtor": {
      "iban": "GB71CLRB04082700001159",
      "paymentAmount": {
        "currencyCode": "GBP",
        "amount": 500.00
      },
      "paymentReference": "Invoice 2025-001"
    },
    "creditor": {
      "accountName": "John Smith",
      "accountNumber": "55779911",
      "sortCode": "200000"
    }
  }'

{
  "Payment": {
    "PaymentId": "764b7d22-9fa0-43bb-920e-326e8634b0f8",
    "Reference": "CLIENT-001",
    "Debtor": {
      "Iban": "GB71CLRB04082700001159",
      "PaymentAmount": {
        "CurrencyCode": "GBP",
        "Amount": 500.00
      },
      "PaymentReference": "Invoice 2025-001",
      "Name": "Acme Ltd"
    },
    "Creditor": {
      "AccountName": "John Smith",
      "AccountNumber": "55779911",
      "SortCode": "200000",
      "Iban": "GB60BARC20000055779911"
    },
    "Status": "Pending",
    "Message": "Payment has been successfully requested and is now being processed"
  }
}

Initial statusPending (async processing)

Max amountGBP 1,000,000 per payment

Track viaWebhooks (TransactionSettled, etc.)

Error responses

All endpoints use the same error format. Here are the responses you will see when something goes wrong:

{
  "status": "Error",
  "message": "Request validation failed",
  "errors": [
    {
      "propertyName": "externalReference",
      "errorDescription": "External reference is required"
    },
    {
      "propertyName": "associates",
      "errorDescription": "At least one associate is required"
    }
  ]
}

{
  "status": "Error",
  "message": "Authentication failed. Check your API key, nonce, and signature."
}

"Internal server error"

Handling errors in your integration

400Check the errors array for specific field-level issues. Fix and retry.

401Signature mismatch. Verify payload order, method case, and body encoding. Use the Helper Tool to compare.

500Server-side issue. Wait briefly, then retry. If persistent, contact API support.

Ready to build?

These examples cover the core flow: onboard a client, open an account, send a payment. Explore the full API reference for all available endpoints.

API Reference Authentication Guide