Architecture patterns

# Recommended mapping tables for your database

clients = {
    "your_customer_id": "cust_abc123",         # Your internal ID
    "mercury_identifier": "CLIENT-001",         # From POST /api/v1/client response
    "external_reference": "EXT-REF-001",        # What you sent in externalReference
    "status": "Active",                         # Track via Clients.ClientStatusChanged
    "gbp_iban": "GB71CLRB04082700001159",       # From Accounts.AccountCreated webhook
    "eur_iban": "GB85CLRB04274893940059",       # From Accounts.AccountCreated webhook
}

payments = {
    "your_payment_id": "pay_xyz789",            # Your internal ID
    "mercury_payment_id": "764b7d22-...",       # From payment submission response
    "end_to_end_id": "E2E-20260419-001",       # What you sent (must be unique, ever)
    "client_reference": "CLIENT-001",           # Links back to client
    "currency": "GBP",
    "amount": 500.00,
    "status": "Pending",                        # Track via webhook events
    "created_at": "2026-04-19T10:30:00Z",
    "settled_at": None,                         # Set when TransactionSettled arrives
}

// Recommended mapping tables for your database

const client = {
  yourCustomerId: "cust_abc123",           // Your internal ID
  mercuryIdentifier: "CLIENT-001",         // From POST /api/v1/client response
  externalReference: "EXT-REF-001",        // What you sent in externalReference
  status: "Active",                        // Track via Clients.ClientStatusChanged
  gbpIban: "GB71CLRB04082700001159",       // From Accounts.AccountCreated webhook
  eurIban: "GB85CLRB04274893940059",       // From Accounts.AccountCreated webhook
};

const payment = {
  yourPaymentId: "pay_xyz789",             // Your internal ID
  mercuryPaymentId: "764b7d22-...",        // From payment submission response
  endToEndId: "E2E-20260419-001",          // What you sent (must be unique, ever)
  clientReference: "CLIENT-001",           // Links back to client
  currency: "GBP",
  amount: 500.00,
  status: "Pending",                       // Track via webhook events
  createdAt: "2026-04-19T10:30:00Z",
  settledAt: null,                         // Set when TransactionSettled arrives
};

// Recommended mapping tables for your database

public class MercuryClient {
    private String yourCustomerId;          // "cust_abc123" - Your internal ID
    private String mercuryIdentifier;       // "CLIENT-001" - From POST /api/v1/client
    private String externalReference;       // "EXT-REF-001" - What you sent
    private String status;                  // "Active" - Track via ClientStatusChanged
    private String gbpIban;                 // From Accounts.AccountCreated webhook
    private String eurIban;                 // From Accounts.AccountCreated webhook
}

public class MercuryPayment {
    private String yourPaymentId;           // "pay_xyz789" - Your internal ID
    private String mercuryPaymentId;        // "764b7d22-..." - From payment response
    private String endToEndId;              // "E2E-20260419-001" - Must be unique, ever
    private String clientReference;         // "CLIENT-001" - Links back to client
    private String currency;                // "GBP"
    private BigDecimal amount;              // 500.00
    private String status;                  // "Pending" - Track via webhook events
    private Instant createdAt;
    private Instant settledAt;              // Set when TransactionSettled arrives
}

import json
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

# Track processed events to handle duplicates
processed_events = set()

@app.route("/webhooks/mercury", methods=["POST"])
def handle_webhook():
    payload = request.get_json()
    event_type = payload.get("Type")
    nonce = payload.get("Nonce")

    # 1. Deduplicate using nonce
    if nonce in processed_events:
        return jsonify({"received": True}), 200

    # 2. Acknowledge immediately (Mercury checks HTTP status only)
    # In production, queue the event for async processing
    processed_events.add(nonce)

    # 3. Route by event type
    handlers = {
        "ClientCreated": handle_client_created,
        "AccountCreated": handle_account_created,
        "PaymentTransactionSettled": handle_payment_settled,
        "PaymentTransactionRejected": handle_payment_rejected,
        "MccyOutboundPaymentComplete": handle_mccy_payment_complete,
        "MccyOutboundPaymentFailed": handle_mccy_payment_failed,
    }

    handler = handlers.get(event_type)
    if handler:
        handler(payload["Payload"])

    return jsonify({"received": True}), 200


def handle_account_created(data):
    """Store the IBAN - you need it for payments."""
    client_ref = data["OwnerReference"]
    iban = data["Identifiers"][0]["Identifier"]
    currency = data["Currencies"][0]
    # Update your database: link IBAN to client
    print(f"Account ready: {client_ref} -> {iban} ({currency})")


def handle_payment_settled(data):
    """Mark payment as complete in your system."""
    payment_id = data["PaymentId"]
    e2e_id = data["EndToEndTransactionId"]
    settled_at = data["TimestampSettled"]
    # Update your database: payment status -> Settled
    print(f"Payment settled: {payment_id} (E2E: {e2e_id})")

const express = require("express");
const app = express();
app.use(express.json());

// Track processed events to handle duplicates
const processedEvents = new Set();

app.post("/webhooks/mercury", (req, res) => {
  const { Type: eventType, Payload: payload, Nonce: nonce } = req.body;

  // 1. Deduplicate using nonce
  if (processedEvents.has(nonce)) {
    return res.json({ received: true });
  }

  // 2. Acknowledge immediately (Mercury checks HTTP status only)
  // In production, queue the event for async processing
  processedEvents.add(nonce);

  // 3. Route by event type
  const handlers = {
    ClientCreated: handleClientCreated,
    AccountCreated: handleAccountCreated,
    PaymentTransactionSettled: handlePaymentSettled,
    PaymentTransactionRejected: handlePaymentRejected,
    MccyOutboundPaymentComplete: handleMccyPaymentComplete,
    MccyOutboundPaymentFailed: handleMccyPaymentFailed,
  };

  const handler = handlers[eventType];
  if (handler) handler(payload);

  res.json({ received: true });
});

function handleAccountCreated(data) {
  // Store the IBAN - you need it for payments
  const clientRef = data.OwnerReference;
  const iban = data.Identifiers[0].Identifier;
  const currency = data.Currencies[0];
  // Update your database: link IBAN to client
  console.log(`Account ready: ${clientRef} -> ${iban} (${currency})`);
}

function handlePaymentSettled(data) {
  // Mark payment as complete in your system
  const { PaymentId: paymentId, EndToEndTransactionId: e2eId, TimestampSettled: settledAt } = data;
  // Update your database: payment status -> Settled
  console.log(`Payment settled: ${paymentId} (E2E: ${e2eId})`);
}

import os

# Environment-driven configuration
MERCURY_CONFIG = {
    "base_url": os.environ.get(
        "MERCURY_BASE_URL",
        "https://www.api.external.test.mercury.global"  # sandbox default
    ),
    "api_key": os.environ.get("MERCURY_API_KEY"),
    "secret_key": os.environ.get("MERCURY_SECRET_KEY"),
}

# Same code, different credentials
def get_base_url():
    return MERCURY_CONFIG["base_url"]

// Environment-driven configuration
const mercuryConfig = {
  baseUrl: process.env.MERCURY_BASE_URL
    || "https://www.api.external.test.mercury.global",  // sandbox default
  apiKey: process.env.MERCURY_API_KEY,
  secretKey: process.env.MERCURY_SECRET_KEY,
};

// Same code, different credentials
const getBaseUrl = () => mercuryConfig.baseUrl;