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:

EventDescription
statusChangedHappens 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:

FieldDescription
uuidUUID of the linked payment, will remain the same across all webhook types for that payment.
typeThe type of payment, can be IN for deposit or OUT for withdrawal
statusThe current status of the payment.COMPLETE statuses are final.
displayCurrencyThe amounts in the selected display currency that the end user will see.
paidCurrencyThe amounts in the currency actually sent by the end user when fulfilling the payment.
walletCurrencyThe amounts in the settlement or wallet currency linked to the payment.
amountThe amount requested when creating a payment.
actualThe actual amount of money sent once the payment is confirmed on the blockchain.

Payment Flow Diagram and Webhooks Sent

Diagram of the payment out lifecycle.

Diagram of the payment out lifecycle.


Payment Complete Webhooks

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

Webhook Event NameDescription
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": []
  }
}