Listening for Payout Webhooks

Get notified of all state changes in the payment journey

Layer1 sends out a series of webhooks to keep you informed on any lifecycle event for the payment you have created.

The body of a webhook can be divided into two main different sections, event and data. The event will be what event has occurred within the product source of the webhook, and data will be all of the relevant payment information sent with the webhook.

Event types:

Event	Description
layer1:payment:checkout:status-change	Happens twice, the status of the payment changes from pending to processing, or from processing to complete.
layer1:payment:checkout:transaction-held	A payment has been placed on hold for screening.

Data types

Data in each webhook is comprehensive, but we will highlight some of the most important fields here:

Field	Description
uuid	UUID of the linked payment, will remain the same across all webhook types for that payment.
type	The type of payment, can be IN for deposit or OUT for payout
status	The current status of the payment.
displayCurrency	The amounts in the selected display currency that the end user will see.
paidCurrency	The amounts in the digital asset sent by the merchant to end-user.
walletCurrency	The amounts debited from wallet used to fund the payment.
amount	The amount requested when creating a payment.
actual	The actual amount of money sent once the payment is confirmed on the blockchain.
transactions	The array of transactions linked to the payment, if multiple payments are sent to the same address, they will all appear here.

Payment Flow Diagram and Webhooks Sent

Webhook Sequence for Each Scenario

Payment Complete Webhooks

Upon the end user successfully completing the payment within the allocated time frame and with the correct amount, you'll receive the following webhooks:

1. statusChanged - Processing: Dispatched when the payment status updates to processing after the transaction is recognized on the platform.
2. statusChanged - Complete: Issued when the payment status updates to complete following blockchain confirmation.

The statusChanged - Complete webhook delivers comprehensive payment details, including the final amounts sent (actual fields) and the transaction hash within the transactions array.

Payout Webhook Examples:

statusChanged - PROCESSING

{
  "event": "layer1:payment:checkout:status-change",
  "eventId": "01977e61-0ef9-77a2-90bb-9933922f72ae",
  "timestamp": "2025-06-17T14:52:59.513989735Z",
  "data": {
    "uuid": "f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "merchantDisplayName": "USDT wallet",
    "merchantId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358",
    "dateCreated": 1750171979150,
    "expiryDate": 1750173179150,
    "quoteExpiryDate": 1750173179150,
    "acceptanceExpiryDate": 1750172009214,
    "quoteStatus": "ACCEPTED",
    "reference": "437f100c-e37e-401e-9b32-aec349843d05",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "USDT",
      "amount": 11.57236634640142803,
      "actual": 11.57236634640142803
    },
    "paidCurrency": {
      "currency": "USDT",
      "amount": 11.57236634640142803,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "USDT",
      "amount": 0.381888089039204284,
      "actual": 0
    },
    "networkFeeCurrency": {
      "currency": "USDT",
      "amount": 1.15723663,
      "actual": 0
    },
    "displayRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.864127525866
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "USDT",
      "rate": 1
    },
    "address": {
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": "",
      "protocol": "ERC20",
      "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x84A4a239805d06c685219801B82BEA7c76702214&uint256=11572366",
      "alternatives": []
    },
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.layer1.com/payout/f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": null,
    "flow": null,
    "twoStep": false,
    "metadata": {},
    "customerId": null,
    "pegged": false
  }
}

statusChanged - COMPLETE

{
  "event": "layer1:payment:checkout:status-change",
  "eventId": "01977e62-0af9-7c58-81c1-aa200fc2d5a7",
  "timestamp": "2025-06-17T14:54:04.025185418Z",
  "data": {
    "uuid": "f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "merchantDisplayName": "USDT wallet",
    "merchantId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358",
    "dateCreated": 1750171979150,
    "expiryDate": 1750173179150,
    "quoteExpiryDate": 1750173179150,
    "acceptanceExpiryDate": 1750172009215,
    "quoteStatus": "ACCEPTED",
    "reference": "437f100c-e37e-401e-9b32-aec349843d05",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 10
    },
    "walletCurrency": {
      "currency": "USDT",
      "amount": 11.572366,
      "actual": 11.572366
    },
    "paidCurrency": {
      "currency": "USDT",
      "amount": 11.572366,
      "actual": 11.572366
    },
    "feeCurrency": {
      "currency": "USDT",
      "amount": 0.381888,
      "actual": 0.38188799
    },
    "networkFeeCurrency": {
      "currency": "USDT",
      "amount": 1.157237,
      "actual": 1.157237
    },
    "displayRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.864127525866
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "USDT",
      "rate": 1
    },
    "address": {
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": "",
      "protocol": "ERC20",
      "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x84A4a239805d06c685219801B82BEA7c76702214&uint256=11572366",
      "alternatives": []
    },
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.layer1.com/payout/f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "transactions": [
      {
        "dateCreated": 1750172044013,
        "dateConfirmed": 1750172043977,
        "hash": "0xff970e401af21112a245085c08be1129dc1421750f379f58df2fc2c9f87f3e27",
        "amount": 11.572366,
        "networkFeeCurrency": "USDT",
        "networkFeeAmount": null,
        "sources": [
          "0xfb64535b1466a9aaf39f84fce15b971b341ca9fc",
          "0xfb64535b1466a9aaf39f84fce15b971b341ca9fc"
        ],
        "displayRate": {
          "base": "USDT",
          "counter": "EUR",
          "rate": 0.864127525866
        },
        "exchangeRate": {
          "base": "USDT",
          "counter": "USDT",
          "rate": 1
        },
        "protocol": "ERC20",
        "isOnHold": false
      }
    ],
    "refund": null,
    "refunds": [],
    "currencyOptions": null,
    "flow": null,
    "twoStep": false,
    "metadata": {},
    "customerId": null,
    "pegged": false
  }
}

transactionOnHold

{
  "event": "layer1:payment:checkout:transaction-held",
  "eventId": "01977e62-0af9-7c58-81c1-aa200fc2d5a7",
  "timestamp": "2025-06-17T14:54:04.025185418Z",
  "data": {
    "uuid": "f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "merchantDisplayName": "USDT wallet",
    "merchantId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358",
    "dateCreated": 1750171979150,
    "expiryDate": 1750173179150,
    "quoteExpiryDate": 1750173179150,
    "acceptanceExpiryDate": 1750172009215,
    "quoteStatus": "ACCEPTED",
    "reference": "437f100c-e37e-401e-9b32-aec349843d05",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 10
    },
    "walletCurrency": {
      "currency": "USDT",
      "amount": 11.572366,
      "actual": 11.572366
    },
    "paidCurrency": {
      "currency": "USDT",
      "amount": 11.572366,
      "actual": 11.572366
    },
    "feeCurrency": {
      "currency": "USDT",
      "amount": 0.381888,
      "actual": 0.38188799
    },
    "networkFeeCurrency": {
      "currency": "USDT",
      "amount": 1.157237,
      "actual": 1.157237
    },
    "displayRate": {
      "base": "USDT",
      "counter": "EUR",
      "rate": 0.864127525866
    },
    "exchangeRate": {
      "base": "USDT",
      "counter": "USDT",
      "rate": 1
    },
    "address": {
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": "",
      "protocol": "ERC20",
      "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x84A4a239805d06c685219801B82BEA7c76702214&uint256=11572366",
      "alternatives": []
    },
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.layer1.com/payout/f92f0ac0-8f91-43d2-b73c-75061c222d47",
    "transactions": [
      {
        "dateCreated": 1750172044013,
        "dateConfirmed": 1750172043977,
        "hash": "0xff970e401af21112a245085c08be1129dc1421750f379f58df2fc2c9f87f3e27",
        "amount": 11.572366,
        "networkFeeCurrency": "USDT",
        "networkFeeAmount": null,
        "sources": [
          "0xfb64535b1466a9aaf39f84fce15b971b341ca9fc",
          "0xfb64535b1466a9aaf39f84fce15b971b341ca9fc"
        ],
        "displayRate": {
          "base": "USDT",
          "counter": "EUR",
          "rate": 0.864127525866
        },
        "exchangeRate": {
          "base": "USDT",
          "counter": "USDT",
          "rate": 1
        },
        "protocol": "ERC20",
        "isOnHold": true
      }
    ],
    "refund": null,
    "refunds": [],
    "currencyOptions": null,
    "flow": null,
    "twoStep": false,
    "metadata": {},
    "customerId": null,
    "pegged": false
  }
}
  "data": {
    "uuid": "b078499c-0c6c-4e3f-8a32-66dca1d2676b",
    "merchantDisplayName": "ETH Merchant ",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "dateCreated": 1709543074000,
    "expiryDate": 1709715874000,
    "quoteExpiryDate": 1709715874000,
    "acceptanceExpiryDate": 1709543139000,
    "quoteStatus": "ACCEPTED",
    "reference": "REF958403",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "ETH",
      "amount": 0.01,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "ETH",
      "amount": 0.01,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.01,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "ETH",
      "amount": 0.0001,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "exchangeRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "address": {
      "address": "0xc643e89d9499d1e888c0be5c89b0d49973115d8a",
      "tag": null,
      "protocol": "ETH",
      "uri": "ethereum:0xc643e89d9499d1e888c0be5c89b0d49973115d8a?value=1E+16",
      "alternatives": []
    },
    "returnUrl": "",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=b078499c-0c6c-4e3f-8a32-66dca1d2676b&hpp=true",
    "transactions": [
      {
        "dateCreated": 1709543141000,
        "dateConfirmed": null,
        "hash": "0xfc403fb78ce3d05205c90ae91ddaf5f9760fd00ca15714b01951415ff3dbd172",
        "amount": 0.01,
        "risk": null,
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": null,
        "sources": null,
        "displayRate": {
          "base": "ETH",
          "counter": "ETH",
          "rate": 1
        },
        "exchangeRate": {
          "base": "ETH",
          "counter": "ETH",
          "rate": 1
        },
        "protocol": "ETH",
        "isOnHold": true
      }
    ],
    "refund": null,
    "refunds": []
  }
}

statusChanged - EXPIRED

{
  "event": "layer1:payment:checkout:status-change",
  "eventId": "01977e6b-23d6-70af-94c4-0d6003fc2eec",
  "timestamp": "2025-06-17T15:04:00.214983264Z",
  "data": {
    "uuid": "63e3fece-1e91-4d57-9bd9-35d785183486",
    "merchantDisplayName": "USDT wallet",
    "merchantId": "ce3fe53f-2461-46d7-9e8a-0e58003cd358",
    "dateCreated": 1750171431459,
    "expiryDate": 1750172640132,
    "quoteExpiryDate": null,
    "acceptanceExpiryDate": null,
    "quoteStatus": "TEMPLATE",
    "reference": "9a983440-7149-415a-9cdc-f445c9d87ad8",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "EXPIRED",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "USDT",
      "amount": 11.57236634640142803,
      "actual": 0
    },
    "paidCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "USDT",
      "amount": 0,
      "actual": 0
    },
    "networkFeeCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "displayRate": null,
    "exchangeRate": null,
    "address": null,
    "returnUrl": "https://yourwebsitename.com",
    "redirectUrl": "https://pay.sandbox.layer1.com/payout/63e3fece-1e91-4d57-9bd9-35d785183486",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": null,
    "flow": null,
    "twoStep": false,
    "metadata": {},
    "customerId": null,
    "pegged": false
  }
}