Receive Payout Notifications

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

Webhook structure

The body of a webhook can be divided into three different sections:

• source. Specifies the product source of the webhook.
• event: Specifies an event that occurred within that source.
• data. Indicates relevant payment information sent with the webhook.

Source types

For a payout, the source will always be payment.

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.

Data types

Data in each webhook is comprehensive. Note the most important fields here:

Field	Description
uuid	UUID of the linked payment. Remains the same across all webhook types for that payment
type	Type of payment, can be IN for deposit or OUT for withdrawal
status	Current status of the payment. The COMPLETE status is final
displayCurrency	Amounts in the selected display currency that the end user sees
paidCurrency	Amounts in the currency actually sent by the end user when fulfilling the payment
walletCurrency	Amounts in the settlement or wallet currency linked to the payment
amount	Amount requested when creating a payment
actual	Actual amount of money sent once the payment is confirmed on the blockchain

Payout flow

Diagram of the payment out lifecycle.

Sequence for the Payment Complete webhook

When the end user claims the payout, 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. This webhook provides detailed information about the payment, including the transaction hash, which can be verified using a block explorer within the transactions array

👍

For payout payments, exception scenarios, such as payment failures or errors, are not applicable and thus do not require consideration.

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

statusChanged - PROCESSING

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

statusChanged - COMPLETE

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