Callbacks & Webhooks

Mercuryo sends a POST request to your callback URL every time a transaction status changes. Callbacks are the recommended way to track transaction states.

Setup

1. Sign in to the Dashboard.
2. Go to Widgets → select your widget.
3. Fill in the Callback URL field with your server endpoint.
4. Copy the Sign Key — you'll need it to verify incoming callbacks.

Go to Widget Callbacks to browse callback history, resend a callback, or send a test callback.

Transaction Callback Payload

For the full payload schema and examples for all transaction types, see Callback Reference.

Identifying Transaction Types

In callbacks, transactions are identified by a combination of type and payment_method fields. See Transaction Types & Statuses for the full reference table.

Note: Spend Card event callbacks (card status changes, card top-ups, card payments) use a separate callback URL and payload format. See Spend Card → Event Callbacks.

Callback Delivery & Retry Logic

Mercuryo considers a callback successfully delivered when your server responds with HTTP 200. For any other response code, the system retries automatically:

You can also manually resend callbacks from the Dashboard.

Callback Signature Verification

Each callback includes an X-Signature header containing an HMAC SHA-256 hash of the raw JSON body, generated using your Sign Key.

Important: Use the complete raw JSON body exactly as received — do not parse, reformat, or extract fields from it. Any modification will produce a different hash and cause verification to fail.

JavaScript

const crypto = require('crypto');

function verifyCallbackSignature(rawBody, signature, signKey) {
  const hmac = crypto.createHmac('sha256', signKey);
  const calculated = hmac.update(rawBody).digest('hex');
  return calculated === signature;
}

Python

import hmac
import hashlib

def verify_callback_signature(raw_body: str, signature: str, sign_key: str) -> bool:
    calculated = hmac.new(sign_key.encode(), raw_body.encode(), hashlib.sha256).hexdigest()
    return calculated == signature

Go

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func verifyCallbackSignature(rawBody, signature, signKey string) bool {
    h := hmac.New(sha256.New, []byte(signKey))
    h.Write([]byte(rawBody))
    return hex.EncodeToString(h.Sum(nil)) == signature
}

Try It: Callback Signature Calculator

Paste your raw callback body and Sign Key to verify your implementation.

Note: The hash is computed locally using your browser.