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 only
`X-Transaction-Id`	Idempotency key for the underlying transaction.	Deposit webhooks only

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

We emit three webhook events for deposits:

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.

`DEPOSIT_TX_SUBMITTED` Payload Example

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

`DEPOSIT_TX_CONFIRMED` Payload Example

JSON

{
  "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)
}

Amount finality: DEPOSIT_TX_SUBMITTED.grossAmount is the minimum expected destination amount. The final settled amount is provided in DEPOSIT_TX_CONFIRMED.amount and may be slightly higher.

`DEPOSIT_TX_ENRICHED` Payload Example

This event includes an incomingTransactions array containing on-chain transaction details. This data can be used to reconcile deposits, track confirmation details, and build reliable transaction histories.

JSON

{
  "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

API

WALLET

CURRENCY

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

Overview

Webhook Request Headers

Pay Link Webhook Payload Example

Deposit Webhooks

`DEPOSIT_TX_SUBMITTED` Payload Example

`DEPOSIT_TX_CONFIRMED` Payload Example

`DEPOSIT_TX_ENRICHED` Payload Example

Authenticating Webhooks with Bearer Token

Retrieving Geolocation from the Webhook Payload

API

WALLET

CURRENCY

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

​Webhook Request Headers

​Pay Link Webhook Payload Example

​Deposit Webhooks

​DEPOSIT_TX_SUBMITTED Payload Example

​DEPOSIT_TX_CONFIRMED Payload Example

​DEPOSIT_TX_ENRICHED Payload Example

​Authenticating Webhooks with Bearer Token

​Retrieving Geolocation from the Webhook Payload

Webhook Request Headers

Pay Link Webhook Payload Example

Deposit Webhooks

`DEPOSIT_TX_SUBMITTED` Payload Example

`DEPOSIT_TX_CONFIRMED` Payload Example

`DEPOSIT_TX_ENRICHED` Payload Example

Authenticating Webhooks with Bearer Token

Retrieving Geolocation from the Webhook Payload