Listening for Payout Webhooks

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 has changed, either from `PENDING` to `PROCESSING`, `PENDING` to `EXPIRED`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 withdrawal
`status`	The current status of the payment. `EXPIRED`, `UNDERPAID` and `COMPLETE` statuses are all final.
`displayCurrency`	The amounts in the selected display currency that the end user will see.
`paidCurrency`	The amounts in the currency actually sent by the end user when fulfilling the payment.
`walletCurrency`	The amounts in the settlement or wallet currency linked to 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:

statusChanged - Processing: Dispatched when the payment status updates to processing after the transaction is recognized on the platform.
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.

Payment In Webhook Examples

The following is a comprehensive collection of the data sent for all of the webhooks mentioned on this page:

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

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

{
  "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": []
  }
}

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