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 changes 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 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:
- 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.
Payout webhook examples
status-change - PROCESSING
status-change - 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
}
}
status-change - COMPLETE
status-change - 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
}
}
transaction-held
transaction-held
{
"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
}
}
status-change - EXPIRED
status-change - 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
}
}