Webhooks

Mercuryo sends JSON POST notifications to the callback URL configured with your integration manager. Payment and refund notifications use the same envelope and signature. Notifications can also report an intermediate status; their status is a snapshot and may already be older than the current GET status response.

• Not the only channel. A notification can be delayed. Start polling GET /sdk-partner/alternative-mobile-pay/mobile-pay/{id}/status 5 seconds after the create and continue until the status is final — see Payment statuses. A webhook brings the result sooner when it arrives first.
• Signature. Verify the X-Signature header as the HMAC-SHA256 of the whole raw body as received, using your Sign Key. See Webhook signature. The content type is application/json.
• Acknowledgement. Respond with any 2xx once you have processed the notification or stored it durably; answer duplicates the same way. On a delivery failure or a non-2xx response, delivery is retried with increasing delay.
• Duplicates. The same notification can arrive more than once, with the same eventId when a delivery is retried. Process each operation and its status changes idempotently, including notifications received after your own timeout. Do not assume that a newly generated notification for the same operation will always reuse an earlier eventId.

Payment webhook

Use Payment statuses to handle final outcomes. A Google Pay redirect_pending notification means the buyer has a 3DS step: read redirect_data from GET /sdk-partner/alternative-mobile-pay/mobile-pay/{id}/status and send the buyer to redirect_data.url — see Google Pay. Keep polling GET status for the final status.

Example of a completed Apple Pay payment (method_code is google for Google Pay):

{
  "data": {
    "amount": "10.00000000",
    "fiat_amount": "10.00",
    "id": "28a3c125a28075453",
    "type": "buy",
    "merchant_transaction_id": "order-8841",
    "currency": null,
    "network": null,
    "fiat_currency": "USD",
    "payment_method": "mobile_pay",
    "method_code": "apple",
    "status": "paid",
    "user": {
      "country_code": "",
      "email": "john.doe@example.com",
      "uuid4": "8eb1b522f60d11fa897de1dc6351b7e8"
    },
    "tx": {
      "id": "28a3c125a28075453"
    },
    "fee": null,
    "partner_fee": null,
    "rate": null,
    "card_masked_pan": null,
    "contract_address": null,
    "created_at": "2026-07-07 12:32:47",
    "created_at_ts": 1783427567,
    "updated_at": "2026-07-07 12:35:04",
    "updated_at_ts": 1783427704,
    "masked_dpan": "424242******4242"
  },
  "eventId": "3f9a1b2c4d5e6f78a0"
}

Refund webhook (type: refund)

A refund notification reports the refund operation's final status (succeeded or failed). data.id is the refund id and data.merchant_transaction_id is your merchant_refund_id. The tx.related_id and tx.related_merchant_trx_id fields identify the original payment.

{
  "data": {
    "amount": "5.00000000",
    "fiat_amount": "5.00",
    "id": "c9051779-c818-4edb-8133-2e309f70f484",
    "type": "refund",
    "merchant_transaction_id": "refund-1",
    "currency": null,
    "network": null,
    "fiat_currency": "USD",
    "payment_method": "mobile_pay",
    "method_code": "apple",
    "status": "succeeded",
    "user": {
      "country_code": "",
      "email": "john.doe@example.com",
      "uuid4": "8eb1b522f60d11fa897de1dc6351b7e8"
    },
    "tx": {
      "id": "c9051779-c818-4edb-8133-2e309f70f484",
      "related_id": "28a3c125a28075453",
      "related_merchant_trx_id": "order-8841"
    },
    "fee": null,
    "partner_fee": null,
    "rate": null,
    "card_masked_pan": null,
    "contract_address": null,
    "created_at": "2026-07-07 12:32:47",
    "created_at_ts": 1783427567,
    "updated_at": "2026-07-07 12:35:04",
    "updated_at_ts": 1783427704
  },
  "eventId": "f3a91c2b7d0e845a11"
}

If an expected result does not arrive, follow the timeout guidance or contact support with the refund id. A local timeout is not a failed-operation notification.