For an overview of our Webhooks, view our Guide. For code samples, explore our Recipes.

Webhooks are linked to your MoonPay Commerce account and are authenticated using a sharedToken — included as both a Bearer token in the Authorization header and as the key for the HMAC signature in the X-Signature header. You can generate your API key in the dashboard. Webhooks are supported for Pay Links on Solana, Ethereum, Base, Polygon, and BTC, as well as Subscriptions on Solana.

Webhook Request Headers

Every webhook delivery includes the following HTTP headers:

Header	Description	Included In
`Authorization`	`Bearer <sharedToken>` — authenticates that the request originates from MoonPay Commerce.	All webhooks
`Content-Type`	Always `application/json`.	All webhooks
`X-Signature`	HMAC-SHA256 hex digest of the request body, keyed with your `sharedToken`. Use this to verify payload integrity.	Pay Link & Deposit webhooks
`X-Webhook-Delivery-Id`	Idempotency key for the webhook delivery, in the format `<event>:<key>`.	Deposit webhooks (`DEPOSIT_TX_*`, `DEPOSIT_BELOW_MINIMUM`, and quota events)
`X-Transaction-Id`	Idempotency key for grouping or deduplication. For `DEPOSIT_TX_*`, the underlying transaction meta id; for `DEPOSIT_BELOW_MINIMUM`, the per-fire notification id.	`DEPOSIT_TX_*` and `DEPOSIT_BELOW_MINIMUM`; not sent for quota alerts

For a step-by-step guide on verifying the X-Signature header with code examples in Node.js and Python, see Verifying Webhook Signatures in the Webhooks guide.

Pay Link Webhook Payload Example

Our webhooks include detailed information about the transaction and Pay Link — for regular Pay Links there is the CREATED event, and for subscriptions there are the STARTED, RENEWED, and ENDED events.

JSON

{  // the PaylinkEventPayload object
  "transaction": "...",  // JSON string of the transactionObject below
  "event": "CREATED", // PaylinkEvents enum - matches the webhook event type when creating the webhook
  "transactionObject": {
    "id": "65e1df4d0ce08148bc333b62",  // transaction ID
    "paylinkId": "65dc9f9f1154beaac39976c8", // Paylink ID
		"fee": "1000", // Fee (base units)
    "quantity": 1,
    "createdAt": "2024-03-01T13:59:41.303Z",
    "paymentType": "PAYLINK", // or 'PAYSTREAM'
    "meta": { // the TransactionMeta object
      "id": "65e1df4d0ce08148bc333b60",
      "amount": "9900000", // amount in minimal units (lamport/Sats/Wei)
      "senderPK": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G", // customer's wallet
      "recipientPK": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G", // merchant's recipient wallet
      "customerDetails": { 
        "country": "United States",
        "deliveryAddress": "test-address",
        "email": "test@example.com",
        "fullName": "test-full-name",
        "phoneNumber": "+0123123123123",
        "discordUsername": "a11111118100",
        "discordUser": {
          "id": "1234567890", 
          "username": "test-discord-username"
        },
        "twitterUsername": "test-x-username",
        "state": "test-state",
        "street": "test-street",
        "streetNumber": "123",
        "areaCode": "90210",
        "city": "test-city"
        "additionalJSON": "\"{\\\"test\\\": 123}\"" // any additionalJSON will be JSON stringified
      },
      "productDetails": null,
      "transactionSignature": "5AYzruixQiGX8rm279cPLo7bdqaUPYMD8Z3QnBNVz2omZHaUsUKFZRmaV8W7sAHPEyExeHkjquy8mg6LHcNktg5c",
      "transactionStatus": "SUCCESS",
      "splitRevenue": false,
      "remainingAccounts": [],
      "totalAmount": "9900000",
      "affiliateAmount": "0", // Amount sent to affiliate who referred the transaction. This will normally be "0" unless referred by affiliate
      "affiliateCode": "somecode", // Affiliate code used - this will normally be undefined
      "affiliatePublicKey": "Er3RwfYqCETBTf5RktezXaNDT3zYgwBMftxBYbX8Zk1G"; // Public key (wallet address) for affiliate who referred this transaction. This will normally be undefined
      "tokenQuote": {
        "from": "SOL",
        "fromAmountDecimal": "0.01",
        "to": "SOL",
        "toAmountMinimal": "10000000"
      },
      "submitGeolocation": "FR", // ISO 3166-1 alpha-2 country code based on IP address which submitted the transaction to our server
      "currency": {
        "id": "63430c8348c610068bcdc474",
        "blockchain": null
      }
    }
  }
}

Deposit Webhooks

Deposit webhooks cover three categories: transaction events (per deposit), below-minimum alerts (per deposit wallet), and quota alerts (per company).

Transaction Events

We emit three webhook events when deposit transactions progress:

DEPOSIT_TX_SUBMITTED - when the transaction is broadcast to the network, via swaps.xyz when a bridge or swap is involved.
DEPOSIT_TX_CONFIRMED - when the transaction is confirmed on the blockchain.
DEPOSIT_TX_ENRICHED - when the transaction is enriched with additional data.

Configure these on a deposit-scoped or global deposit webhook (see Create a Deposit Webhook).

Below-Minimum Deposit Alerts

The DEPOSIT_BELOW_MINIMUM is sent when funds have been received in a deposit wallet but the balance has not yet reached the minimum amount required for settlement. Use this event to notify users that additional funds are needed before their deposit can be processed.

When it fires

The event is triggered when:

A deposit wallet receives additional funds.
The wallet balance is above the dust threshold.
The balance remains below the minimum amount required for settlement.

Setup

Below-minimum alerts are delivered through the standard Deposit Webhook endpoint.

Create a deposit webhook using POST /v1/webhook/deposit/api-key (see Create a Deposit Webhook).
Both deposit-scoped webhooks (with a depositId) and global webhooks (without a depositId) receive DEPOSIT_BELOW_MINIMUM when subscribed.
New deposit webhooks default to events: ["ALL"], which includes DEPOSIT_BELOW_MINIMUM. You can subscribe only to DEPOSIT_BELOW_MINIMUM if you prefer.
Authenticate deliveries with Authorization and verify X-Signature like other deposit webhooks.

Below-Minimum Payload Example

JSON

{
  "event": "DEPOSIT_BELOW_MINIMUM", // Webhook event type
  "depositId": "6655001000000000000000c1", // Unique deposit identifier
  "customerId": "merchant-customer-1", // Merchant-defined customer identifier
  "currency": { // Source asset on the deposit wallet (what the user sent)
    "id": "6340313846e4f91b8abc519b",
    "name": "USD Coin",
    "decimals": 6,
    "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "coinMarketCapId": 3408,
    "symbol": "USDC",
    "blockchain": {
      "id": "6340313846e4f91b8abc515c",
      "name": "SOL",
      "symbol": "SOL"
    }
  },
  "originalAmount": "3000000", // Current wallet balance, source-currency minimal units
  "originalAmountInUSD": "3000000", // Current balance in USDC minimal units (6 decimals)
  "minimumAmount": "10000000", // Required minimum in source-currency minimal units (may be omitted)
  "minimumAmountInUSD": "10000000", // Required minimum in USDC minimal units (6 decimals)
  "amount": "0", // Not a settled deposit — always zero
  "feesPaid": "0",
  "gasCharge": "0",
  "grossAmount": "0",
  "webhookDeliveryIdempotencyKey": "DEPOSIT_BELOW_MINIMUM:6655001000000000000000f1",
  "txIdempotencyKey": "6655001000000000000000f1" // Per-fire notification id (same value in X-Transaction-Id)
}

Not a completed deposit: DEPOSIT_BELOW_MINIMUM is fired before any sweep. Use originalAmount and minimumAmount (or their USD fields) to show how much more the user must send - for example, minimumAmount - originalAmount in source units.

Deposit-Customer Quota alerts

Company-level alerts fire when your account approaches its daily deposit-customer creation limit. These are separate from DEPOSIT_TX_* events: they track how many deposit customers you create per UTC day, not individual deposit transactions.

Event	Nominal threshold
`DEPOSIT_CUSTOMER_QUOTA_WARNING`	~80%
`DEPOSIT_CUSTOMER_QUOTA_CRITICAL`	~90%
`DEPOSIT_CUSTOMER_QUOTA_REACHED`	100%

Setup

Quota alerts are delivered through the standard Deposit Webhook endpoint.

Create a global deposit webhook using POST /v1/webhook/deposit/api-key without a depositId
Deposit-scoped webhooks (with a depositId) do not receive quota events.
New deposit webhooks are subscribed to all deposit events (ALL) by default, which includes quota alerts. If you already have a global deposit webhook, you will receive quota events without further configuration.

Behaviour

Alerts are triggered as deposit customers are created throughout the day
Each alert type is sent once per UTC day
Daily limits reset at midnight UTC
Once the limit is reached, further create requests return 429 until reset

Quota Alert Payload Example

The event field is one of DEPOSIT_CUSTOMER_QUOTA_WARNING, DEPOSIT_CUSTOMER_QUOTA_CRITICAL, or DEPOSIT_CUSTOMER_QUOTA_REACHED.

JSON

{
  "event": "DEPOSIT_CUSTOMER_QUOTA_WARNING", //Alert type
  "companyId": "6343e77d91c393456aa56462", // Company identifer
  "currentCount": 800, // Customers created today
  "dailyLimit": 1000, // Daily creation limit
  "percentUsed": 80, // Percentage of limit used
  "resetsAt": "2026-05-24T00:00:00.000Z", //UTC reset time
  "webhookDeliveryIdempotencyKey": "DEPOSIT_CUSTOMER_QUOTA_WARNING:6343e77d91c393456aa56462:2026-05-24T00:00:00.000Z"
}

Deposit Transaction Events & Payloads

These webhook events represent different stages in a deposit transaction lifecycle. The payloads below show the data available at submission, confirmation, and enrichment.

DEPOSIT_TX_SUBMITTED - Initial deposit received and processing started.
DEPOSIT_TX_CONFIRMED - Deposit has been confirmed and settled.
DEPOSIT_TX_ENRICHED - Includes enriched on-chain transaction details for deposit reconciliation, confirmation tracking, and transaction history.

{
  "event": "DEPOSIT_TX_SUBMITTED", // Webhook event type
  "depositId": "dep_1234567890", // Unique deposit identifier
  "customerId": "cust_abc123", // Customer identifier
  "amount": "343000000", // Net destination amount at submission (finalised in CONFIRMED)
  "feesPaid": "7000000", // Fees charged, in smallest unit
  "gasCharge": "0", // Gas fee charged (if applicable), in smallest unit
  "grossAmount": "350000000", // Minimum expected destination amount at submission
  "currency": { // Destination currency (what the user will receive)
    "id": "currency_sol_id", // Internal currency ID
    "name": "Solana", // Currency name
    "decimals": 9, // Currency decimals
    "mintAddress": "11111111111111111111111111111111", // Token mint address (native SOL shown here)
    "coinMarketCapId": 5426, // CoinMarketCap ID
    "symbol": "SOL", // Currency symbol
    "blockchain": {
      "id": "blockchain_sol_id", // Internal blockchain ID
      "name": "SOL", // Blockchain name
      "symbol": "SOL" // Blockchain symbol
    }
  },
  "originalAmount": "343000000", // Original received

{
  "event": "DEPOSIT_TX_CONFIRMED", // Webhook event type

  "depositId": "dep_1234567890", // Unique deposit identifier
  "customerId": "cust_abc123", // Customer identifier (provided by merchant / integrator)

  "amount": "35328965", // Final settled destination amount (source of truth)
  "feesPaid": "706579", // Total fees charged, in smallest unit
  "gasCharge": "0", // Gas fee charged (if applicable), in smallest unit
  "grossAmount": "36035544", // Final destination amount before fees

  "currency": { // Destination currency (what the customer receives)
    "id": "currency_sol_id", // Internal currency ID
    "name": "Solana", // Currency name
    "decimals": 9, // Currency decimals
    "mintAddress": "11111111111111111111111111111111", // Token mint address (native SOL shown here)
    "coinMarketCapId": 5426, // CoinMarketCap ID
    "symbol": "SOL", // Currency symbol

    "blockchain": {
      "id": "blockchain_sol_id", // Internal blockchain ID
      "name": "SOL", // Blockchain name
      "symbol": "SOL" // Blockchain symbol
    }
  },

  "originalAmount": "4993316380000000", // Original received amount (source), in smallest unit of originalCurrency
  "originalAmountInUSD": "3072627", // USD value of originalAmount at time of processing (smallest USD unit, e.g. cents * 100)
  
  "originalCurrency": { // Source currency (what the user originally sent)
    "id": "currency_bnb_id", // Internal currency ID
    "name": "BNB", // Currency name
    "decimals": 18, // Currency decimals
    "mintAddress": "0x0000000000000000000000000000000000000000", // Token contract address (or native placeholder)
    "coinMarketCapId": 1839, // CoinMarketCap ID
    "symbol": "BNB", // Currency symbol

    "blockchain": {
      "id": "blockchain_bsc_id", // Internal blockchain ID
      "name": "BSC", // Blockchain name
      "symbol": "BSC" // Blockchain symbol
    }
  },

  "webhookDeliveryIdempotencyKey": "DEPOSIT_TX_CONFIRMED:tx_abc123", // Idempotency key for webhook delivery
  "txIdempotencyKey": "tx_abc123", // Idempotency key for the transaction
  "submittedTransactionIdempotencyKey": "submitted_tx_abc123", // Idempotency key for submitted transaction (if applicable)

  "transactionObject": { // Transaction details object
    "id": "txn_1234567890", // Internal transaction ID
    "fee": "706579", // Fee amount in smallest unit
    "createdAt": "2026-02-13T16:35:27.561Z", // Timestamp of transaction creation
    "paymentType": "DEPOSIT", // Payment type classification

    "meta": {
      "id": "tx_meta_abc123", // Internal transaction meta ID
      "amount": "35328965", // Deposited amount, in smallest unit
      "senderPK": "0xSenderWalletAddressHere", // Sender wallet address
      "recipientPK": "RecipientWalletAddressHere", // Recipient wallet address
      "transactionType": "DEPOSIT", // Transaction type

      "currency": { // Destination currency object (same as top-level currency)
        "id": "currency_sol_id",
        "name": "Solana",
        "decimals": 9,
        "mintAddress": "11111111111111111111111111111111",
        "coinMarketCapId": 5426,
        "symbol": "SOL",
        "blockchain": {
          "id": "blockchain_sol_id",
          "name": "SOL",
          "symbol": "SOL"
        }
      },

      "transactionSignature": "0xTransactionHashOrSignatureHere", // Blockchain tx hash/signature
      "customerDetails": null, // Optional customer metadata (can be null)
      "productDetails": {}, // Optional product metadata
      "transactionStatus": "SUCCESS", // Transaction status
      "totalAmount": "35328965" // Total processed amount, in smallest unit
    }
  },

  "transaction": "{\"id\":\"txn_1234567890\"...}" // Stringified version of transactionObject (legacy/compat)
}

{
  "event": "DEPOSIT_TX_ENRICHED", // Webhook event type
  "depositId": "69861e434e3b4725275f1e14", // Unique deposit identifier
  "customerId": "test", // Customer identifier

  "amount": "3919234", // Net deposited amount (after fees), in smallest currency unit
  "feesPaid": "78384", // Fees charged, in smallest currency unit
  "gasCharge": "0", // Gas fee charged (if applicable), in smallest currency unit
  "grossAmount": "3997618", // Total amount including fees, in smallest currency unit

  "currency": {
    "id": "6340313846e4f91b8abc519b", // Internal currency ID
    "name": "USD Coin", // Currency name
    "decimals": 6, // Currency decimals
    "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Token mint address
    "coinMarketCapId": 3408, // CoinMarketCap ID
    "symbol": "USDC", // Currency symbol
    "blockchain": {
      "id": "6340313846e4f91b8abc515c", // Internal blockchain ID
      "name": "SOL", // Blockchain name
      "symbol": "SOL" // Blockchain symbol
    }
  },

  "originalAmount": "46185585", // Original received amount (before conversion), in smallest unit of originalCurrency
  "originalAmountInUSD": "3997651", // USD value of originalAmount at time of processing, in cents (or smallest USD unit)
  "originalCurrency": {
    "id": "6340313846e4f91b8abc5195", // Internal currency ID of original asset
    "name": "Solana", // Original asset name
    "decimals": 9, // Original asset decimals
    "mintAddress": "11111111111111111111111111111111", // Original asset mint address
    "coinMarketCapId": 5426, // CoinMarketCap ID
    "symbol": "SOL", // Original asset symbol
    "blockchain": {
      "id": "6340313846e4f91b8abc515c", // Blockchain ID
      "name": "SOL", // Blockchain name
      "symbol": "SOL" // Blockchain symbol
    }
  },

  "transactionObject": {
    "id": "69861ef6cec1fd89b559a8a7", // Internal transaction ID
    "fee": "78384", // Transaction fee, in smallest currency unit
    "createdAt": "2026-02-06T17:03:50.641Z", // Transaction creation timestamp (ISO 8601)
    "paymentType": "DEPOSIT", // Payment type classification
    "meta": {
      "id": "69861ef6cec1fd89b559a8a5", // Internal transaction meta ID
      "amount": "3919234", // Deposited amount, in smallest currency unit
      "senderPK": "Cq9f4fhen7ovueaa3Ug44RE2nEJSPhD41NV5HpLpjgGG", // Sender wallet address
      "recipientPK": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW", // Recipient wallet address
      "transactionType": "DEPOSIT", // Transaction type
      "currency": {
        "id": "6340313846e4f91b8abc519b", // Currency ID
        "name": "USD Coin", // Currency name
        "decimals": 6, // Currency decimals
        "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Token mint address
        "coinMarketCapId": 3408, // CoinMarketCap ID
        "symbol": "USDC", // Currency symbol
        "blockchain": {
          "id": "6340313846e4f91b8abc515c", // Blockchain ID
          "name": "SOL", // Blockchain name
          "symbol": "SOL" // Blockchain symbol
        }
      },
      "transactionSignature": "2NPEMm7XEgz2Hcr3fZ4KdqE6bjxz887YF9vFssipXg1UY5tUtzR8cSbENjHY8ij7qLQMp4VCQqPK18vAwkedkRg1", // Blockchain transaction signature/hash
      "customerDetails": {
        "additionalJSON": "testing" // Customer metadata (custom field)
      },
      "productDetails": {}, // Product metadata (if applicable)
      "transactionStatus": "SUCCESS", // Transaction status
      "totalAmount": "3919234" // Total processed amount, in smallest currency unit
    }
  },

  "transaction": "{\"id\":\"69861ef6cec1fd89b559a8a7\"...}", // Stringified JSON version of transactionObject (legacy/compat)

  "webhookDeliveryIdempotencyKey": "DEPOSIT_TX_ENRICHED:69861ef6cec1fd89b559a8a5", // Idempotency key for webhook delivery
  "txIdempotencyKey": "69861ef6cec1fd89b559a8a5", // Idempotency key for the transaction

  "incomingTransactions": [
    {
      "hash": "4zig5GYQzkJwf2N36X4CuYejCasCcEgnbBmGxQWn32a6S3aJa4RT6cDHweDvr73BNVqKWHdfpNPaH9NK1AJXN57N", // On-chain transaction hash
      "from": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW", // Sender address
      "to": "Cq9f4fhen7ovueaa3Ug44RE2nEJSPhD41NV5HpLpjgGG", // Recipient address
      "value": "46185585", // Amount transferred, in smallest unit of originalCurrency
      "blockNumber": 398484220, // Block/slot number
      "timestamp": 1770397408, // Transaction timestamp (unix epoch seconds)
      "status": "success", // On-chain execution status
      "gasUsed": "5000" // Gas/compute units used (chain-specific)
    }
  ]
}

Authenticating Webhooks with Bearer Token

A unique token generated at webhook creation is included with each webhook request as an Authorization: Bearer SHARED_TOKEN header, verifying that the webhook is sent from us.

JSON

{
    "id": "636cf9c095aeedb263968ee9",
    "paylink": "636a74162e72d4ad24ac9ce9",
    "company": "6343e77d91c393456aa56462",
    "targetUrl": "https://target-url.com/post-endpoint",
    "events": [
        "CREATED"
    ]
    "sharedToken": "PGpDZdZdxjdN+VgoxR/RHItMj0gq2BK5tEZtIisfyKe4M8l0B51qED/YqSSPwfAVtonvdXKhn+9j63b4krxGWNkO3hyPQiiu1SD2uttjEAdMeUO+3QoTNAwxuH1FzwyP"
}

Note: Retain this token, as it is required to authenticate and delete webhooks if needed.

Retrieving Geolocation from the Webhook Payload

The submitGeolocation field in the webhook payload provides the ISO 3166-1 alpha-2 country code representing the location of the IP address that initiated the transaction. This field is useful for understanding the geographic source of transactions. See the code example below, taken from the webhook payload

JSON

"submitGeolocation": "FR"
// ISO 3166-1 alpha-2 country code based on IP address which submitted the 
transaction to our server

JSON

{
  "event": "DEPOSIT_TX_SUBMITTED", // Webhook event type
  "depositId": "dep_1234567890", // Unique deposit identifier
  "customerId": "cust_abc123", // Customer identifier
  "amount": "343000000", // Net destination amount at submission (finalised in CONFIRMED)
  "feesPaid": "7000000", // Fees charged, in smallest unit
  "gasCharge": "0", // Gas fee charged (if applicable), in smallest unit
  "grossAmount": "350000000", // Minimum expected destination amount at submission
  "currency": { // Destination currency (what the user will receive)
    "id": "currency_sol_id", // Internal currency ID
    "name": "Solana", // Currency name
    "decimals": 9, // Currency decimals
    "mintAddress": "11111111111111111111111111111111", // Token mint address (native SOL shown here)
    "coinMarketCapId": 5426, // CoinMarketCap ID
    "symbol": "SOL", // Currency symbol
    "blockchain": {
      "id": "blockchain_sol_id", // Internal blockchain ID
      "name": "SOL", // Blockchain name
      "symbol": "SOL" // Blockchain symbol
    }
  },
  "originalAmount": "343000000", // Original received amount at submission
  "webhookDeliveryIdempotencyKey": "DEPOSIT_TX_SUBMITTED:tx_meta_abc123",
  "txIdempotencyKey": "tx_meta_abc123",
  "submittedTransactionIdempotencyKey": "submitted_tx_abc123"
}

API

WALLET

CURRENCY

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WITHDRAWALS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

Overview

Webhook Request Headers

Pay Link Webhook Payload Example

Deposit Webhooks

Transaction Events

Below-Minimum Deposit Alerts

When it fires

Setup

Below-Minimum Payload Example

Deposit-Customer Quota alerts

Setup

Behaviour

Quota Alert Payload Example

Deposit Transaction Events & Payloads

Authenticating Webhooks with Bearer Token

Retrieving Geolocation from the Webhook Payload

​Webhook Request Headers

​Pay Link Webhook Payload Example

​Deposit Webhooks

​Transaction Events

​Below-Minimum Deposit Alerts

​When it fires

​Setup

​Below-Minimum Payload Example

​Deposit-Customer Quota alerts

​Setup

​Behaviour

​Quota Alert Payload Example

​Deposit Transaction Events & Payloads

​Authenticating Webhooks with Bearer Token

​Retrieving Geolocation from the Webhook Payload

Webhook Request Headers

Pay Link Webhook Payload Example

Deposit Webhooks

Transaction Events

Below-Minimum Deposit Alerts

When it fires

Setup

Below-Minimum Payload Example

Deposit-Customer Quota alerts

Setup

Behaviour

Quota Alert Payload Example

Deposit Transaction Events & Payloads

Authenticating Webhooks with Bearer Token

Retrieving Geolocation from the Webhook Payload