Event Callbacks

In addition to standard transaction callbacks, Mercuryo sends dedicated Spend Card event callbacks. To configure a separate callback URL for these events, contact your integration manager.

For callback setup, signature verification, and retry logic, see Callbacks & Webhooks.

In callbacks, Spend Card transactions are identified by type + payment_method. See Transaction Types for the reference table.

Card Status Change

Sent when the card status changes (e.g., activated, blocked).

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "card_status",
  "card_id": "0c379cbae24f62922",
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66"
  },
  "status": "active",
  "created_at": "2024-06-27 08:26:35",
  "updated_at": "2024-06-27 08:26:41"
}

Crypto Top-Up

Sent when the card balance is replenished via the sell flow.

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "crypto_top_up",
  "card_id": "0c379cbae24f62922",
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66"
  },
  "sell_request": {
    "id": "0daa380ba39596745",
    "merchant_transaction_id": "00357ec76de855485",
    "status": "succeeded",
    "fiat_amount": "130.34",
    "fiat_currency": "EUR",
    "fee": "2",
    "crypto_amount": "0.02",
    "crypto_currency": "BTC"
  },
  "refund_address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9",
  "address": "0xc83935B7295FEC64E32B62C33C24dFdfE04092A9",
  "sender_address": ["0xc83935B7295FEC64E32B62C33C24dFdfE04092A9"],
  "card_balance": "130.34",
  "created_at": "2024-06-27 08:26:35",
  "updated_at": "2024-06-27 08:26:41"
}

Card Transaction

Sent when the card is used for a payment.

{
  "event_id": "80b5ab73-897c-4ec5-aab5-48cc3d0acca8",
  "event_name": "card_transaction",
  "card_id": "0c379cbae24f62922",
  "user": {
    "uuid": "b19ea88b-ed9f-46ad-bfd9-62ddf63ffe66"
  },
  "transaction": {
    "id": "0daa380ba39596745",
    "type": "PURCHASE",
    "status": "AUTHORIZED",
    "decline_reason": null,
    "local_amount": "123",
    "local_currency": "EUR",
    "amount": "123",
    "currency": "EUR",
    "fx_rate": null,
    "mcc": "288",
    "counterparty_name": "Some Shop Name"
  },
  "created_at": "2024-06-27 08:26:35",
  "updated_at": "2024-06-27 08:26:41"
}

Card transaction statuses: AUTHORIZED, CLEARED, DECLINED, REVERSED, INVALID

Transaction Statuses