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 three different sections, source, event , and data. Source will tell you the product source of the webhook, the event will be what event has occurred within that source, and data will be all of the relevant payment information sent with the webhook.

Source types:

For a pay-out, the source will always be payment.

Event types:

Event	Description
`statusChanged`	Happens twice, the status of the payment has changed, either from `pending` to `processing`, or from `processing` to `complete`.

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.`COMPLETE` statuses are 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.

Payment Flow Diagram and Webhooks Sent

Payment Complete Webhooks

When the payout is claimed by the end user, the following webhooks are sent out:

Webhook Event Name	Description
statusChanged - Processing:	Dispatched when the payment status updates to processing after the transaction is recognized on the platform. This occurs when the payout is automatically processed using `payOutDetails`.
statusChanged - Complete:	Dispatched when the payment status updates to complete, indicating that the transaction has been successfully confirmed on the blockchain.

📘
The statusChanged - Complete webhook provides detailed information about the payment, including the transaction hash, which can be verified using a block explorer within the transactions array.

🚧
It's important to note that, for payout payments, exception scenarios (e.g., payment failures or errors) are not applicable and thus do not require consideration.

Payment Out Webhooks

The following is a comprehensive collection of the data sent for all of the webhooks for payouts:

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "07905528-d72e-40dd-a1b4-fb8ec2f748c8",
    "merchantDisplayName": "ETH Merchant ",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "dateCreated": 1709896869000,
    "expiryDate": 1709900469000,
    "quoteExpiryDate": 1709900469000,
    "acceptanceExpiryDate": 1709896938000,
    "quoteStatus": "ACCEPTED",
    "reference": "test_reference_out_mH9LBR1",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "ETH",
      "amount": 0.00276456,
      "actual": 0.00276456
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.00276456,
      "actual": 0
    },
    "feeCurrency": {
      "currency": "ETH",
      "amount": 0.00002765,
      "actual": 0
    },
    "displayRate": {
      "base": "ETH",
      "counter": "EUR",
      "rate": 3617.212142257719
    },
    "exchangeRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "address": {
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": null,
      "protocol": null,
      "uri": "ethereum:0x84A4a239805d06c685219801B82BEA7c76702214?value=2.76456E+15",
      "alternatives": []
    },
    "returnUrl": "www.your-url-here.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=07905528-d72e-40dd-a1b4-fb8ec2f748c8",
    "transactions": [],
    "refund": null,
    "refunds": []
  }
}

{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "07905528-d72e-40dd-a1b4-fb8ec2f748c8",
    "merchantDisplayName": "ETH Merchant ",
    "merchantId": "a7eddadd-fd9b-45fb-82a1-dc12eaa14cba",
    "dateCreated": 1709896869000,
    "expiryDate": 1709900469000,
    "quoteExpiryDate": 1709900469000,
    "acceptanceExpiryDate": 1709896938000,
    "quoteStatus": "ACCEPTED",
    "reference": "test_reference_out_mH9LBR1",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "EUR",
      "amount": 10,
      "actual": 10
    },
    "walletCurrency": {
      "currency": "ETH",
      "amount": 0.00276456,
      "actual": 0.00276456
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.00276456,
      "actual": 0.00276456
    },
    "feeCurrency": {
      "currency": "ETH",
      "amount": 0.00002765,
      "actual": 0.00002765
    },
    "displayRate": {
      "base": "ETH",
      "counter": "EUR",
      "rate": 3617.212142257719
    },
    "exchangeRate": {
      "base": "ETH",
      "counter": "ETH",
      "rate": 1
    },
    "address": {
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": null,
      "protocol": null,
      "uri": "ethereum:0x84A4a239805d06c685219801B82BEA7c76702214?value=2.76456E+15",
      "alternatives": []
    },
    "returnUrl": "www.your-url-here.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=07905528-d72e-40dd-a1b4-fb8ec2f748c8",
    "transactions": [
      {
        "dateCreated": 1709897097718,
        "dateConfirmed": 1709897097718,
        "hash": "0x30c18d5eed6c02418506d69d87c59ee52c2e10753bbccea035346b81c1e1a7e0",
        "amount": 0.00276456,
        "risk": {
          "level": "LOW",
          "resourceName": null,
          "resourceCategory": null,
          "alerts": []
        },
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": 0,
        "sources": [],
        "displayRate": {
          "base": "ETH",
          "counter": "EUR",
          "rate": 3617.212142257719
        },
        "exchangeRate": {
          "base": "ETH",
          "counter": "ETH",
          "rate": 1
        },
        "protocol": null,
        "isOnHold": false
      }
    ],
    "refund": null,
    "refunds": []
  }
}