Listening for payout webhooks

📘
We covered how to create a webhook listener here in the getting setup guide - if you haven't done this already, go back to this step to get ready to receive webhooks.

Webhook Types

In the payout workflow you should expect to receive the following webhooks:

Event	Description
`statusChanged`	The payout has transitioned to a new state.
`transactionOnHold`	The payment has been sent to a high risk address and is held to be further analysed

Webhook Examples

For example:

{
    "source": "payment",
    "event": "statusChanged",
    "data": {
        "uuid": "06f6741c-cbfe-4dbb-b9ae-bd3b11a6f324",
        "merchantDisplayName": "Merchant",
        "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
        "dateCreated": 1720774246668,
        "expiryDate": 1720776046668,
        "quoteExpiryDate": 1720776047000,
        "acceptanceExpiryDate": 1720774277000,
        "quoteStatus": "ACCEPTED",
        "reference": "test_reference_out_js2uNT",
        "type": "OUT",
        "subType": "merchantPayOut",
        "status": "PROCESSING",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 5
        },
        "paidCurrency": {
            "currency": "ETH",
            "amount": 0.00168132,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0.05,
            "actual": 0
        },
        "networkFeeCurrency": {
            "currency": "ETH",
            "amount": 0.00035416,
            "actual": 0
        },
        "displayRate": {
            "base": "ETH",
            "counter": "EUR",
            "rate": 2973.853876715914
        },
        "exchangeRate": {
            "base": "EUR",
            "counter": "ETH",
            "rate": 0.000336263377
        },
        "address": {
            "address": "0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57",
            "tag": "",
            "protocol": "ETH",
            "uri": "ethereum:0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57?value=1.68132E+15",
            "alternatives": []
        },
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=06f6741c-cbfe-4dbb-b9ae-bd3b11a6f324",
        "transactions": [],
        "refund": null,
        "refunds": [],
        "currencyOptions": null,
        "flow": null
    }
}

{
    "source": "payment",
    "event": "statusChanged",
    "data": {
        "uuid": "06f6741c-cbfe-4dbb-b9ae-bd3b11a6f324",
        "merchantDisplayName": "Merchant",
        "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
        "dateCreated": 1720774247000,
        "expiryDate": 1720776047000,
        "quoteExpiryDate": 1720776047000,
        "acceptanceExpiryDate": 1720774277000,
        "quoteStatus": "ACCEPTED",
        "reference": "test_reference_out_js2uNT",
        "type": "OUT",
        "subType": "merchantPayOut",
        "status": "COMPLETE",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 5
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 5
        },
        "paidCurrency": {
            "currency": "ETH",
            "amount": 0.00168132,
            "actual": 0.00132716
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0.05,
            "actual": 0.05
        },
        "networkFeeCurrency": {
            "currency": "ETH",
            "amount": 0.00035416,
            "actual": 0.00035416
        },
        "displayRate": {
            "base": "ETH",
            "counter": "EUR",
            "rate": 2973.853876715914
        },
        "exchangeRate": {
            "base": "EUR",
            "counter": "ETH",
            "rate": 0.000336263377
        },
        "address": {
            "address": "0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57",
            "tag": "",
            "protocol": "ETH",
            "uri": "ethereum:0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57?value=1.68132E+15",
            "alternatives": []
        },
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=06f6741c-cbfe-4dbb-b9ae-bd3b11a6f324",
        "transactions": [
            {
                "dateCreated": 1720776578000,
                "dateConfirmed": 1720776578000,
                "hash": "0xa0b1da63e51e7dc8321a1edd96ffbb164c67ae98d0da4d18bc9a54234e07d6da",
                "amount": 0.00132716,
                "risk": {
                    "level": "UNKNOWN",
                    "resourceName": null,
                    "resourceCategory": null,
                    "alerts": []
                },
                "networkFeeCurrency": "ETH",
                "networkFeeAmount": 0,
                "sources": [],
                "displayRate": {
                    "base": "ETH",
                    "counter": "EUR",
                    "rate": 2973.853876715914
                },
                "exchangeRate": {
                    "base": "EUR",
                    "counter": "ETH",
                    "rate": 0.00033626337665446
                },
                "protocol": null,
                "isOnHold": false
            }
        ],
        "refund": null,
        "refunds": [],
        "currencyOptions": null,
        "flow": null
    }
}

{
    "source": "payment",
    "event": "transactionOnHold",
    "data": {
        "uuid": "2b0c6423-971f-4c79-8a55-8d2278d63128",
        "merchantDisplayName": "Merchant",
        "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
        "dateCreated": 1720780887000,
        "expiryDate": 1720782687000,
        "quoteExpiryDate": 1720782687000,
        "acceptanceExpiryDate": 1720780918000,
        "quoteStatus": "ACCEPTED",
        "reference": "test_reference_out_GyYhiu",
        "type": "OUT",
        "subType": "merchantPayOut",
        "status": "PROCESSING",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 5
        },
        "paidCurrency": {
            "currency": "ETH",
            "amount": 0.00169452,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0.05,
            "actual": 0
        },
        "networkFeeCurrency": {
            "currency": "ETH",
            "amount": 0.00035553,
            "actual": 0
        },
        "displayRate": {
            "base": "ETH",
            "counter": "EUR",
            "rate": 2950.688100465028
        },
        "exchangeRate": {
            "base": "EUR",
            "counter": "ETH",
            "rate": 0.00033890379
        },
        "address": {
            "address": "0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57",
            "tag": "",
            "protocol": "ETH",
            "uri": "ethereum:0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57?value=1.69452E+15",
            "alternatives": []
        },
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=2b0c6423-971f-4c79-8a55-8d2278d63128",
        "transactions": [
            {
                "dateCreated": 1720780961000,
                "dateConfirmed": null,
                "hash": null,
                "amount": 0.00133899,
                "risk": null,
                "networkFeeCurrency": "ETH",
                "networkFeeAmount": 0,
                "sources": [],
                "displayRate": {
                    "base": "ETH",
                    "counter": "EUR",
                    "rate": 2950.688100465028
                },
                "exchangeRate": {
                    "base": "EUR",
                    "counter": "ETH",
                    "rate": 0.000338903789637502
                },
                "protocol": null,
                "isOnHold": true
            }
        ],
        "refund": null,
        "refunds": [],
        "currencyOptions": null,
        "flow": null
    }
}

{
    "source": "payment",
    "event": "statusChanged",
    "data": {
        "uuid": "2b0c6423-971f-4c79-8a55-8d2278d63128",
        "merchantDisplayName": "Merchant",
        "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
        "dateCreated": 1720780887000,
        "expiryDate": 1720782687000,
        "quoteExpiryDate": 1720782687000,
        "acceptanceExpiryDate": 1720780918000,
        "quoteStatus": "ACCEPTED",
        "reference": "test_reference_out_GyYhiu",
        "type": "OUT",
        "subType": "merchantPayOut",
        "status": "CANCELLED",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "paidCurrency": {
            "currency": "ETH",
            "amount": 0.00169452,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0.05,
            "actual": 0
        },
        "networkFeeCurrency": {
            "currency": "ETH",
            "amount": 0.00035553,
            "actual": 0
        },
        "displayRate": {
            "base": "ETH",
            "counter": "EUR",
            "rate": 2950.688100465028
        },
        "exchangeRate": {
            "base": "EUR",
            "counter": "ETH",
            "rate": 0.00033890379
        },
        "address": {
            "address": "0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57",
            "tag": "",
            "protocol": "ETH",
            "uri": "ethereum:0xDCa25Eb963aAcA0F7B12a54fE16674d8bC535c57?value=1.69452E+15",
            "alternatives": []
        },
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=2b0c6423-971f-4c79-8a55-8d2278d63128",
        "transactions": [
            {
                "dateCreated": 1720780961000,
                "dateConfirmed": null,
                "hash": null,
                "amount": 0.00133899,
                "risk": null,
                "networkFeeCurrency": "ETH",
                "networkFeeAmount": 0,
                "sources": [],
                "displayRate": {
                    "base": "ETH",
                    "counter": "EUR",
                    "rate": 2950.688100465028
                },
                "exchangeRate": {
                    "base": "EUR",
                    "counter": "ETH",
                    "rate": 0.000338903789637502
                },
                "protocol": null,
                "isOnHold": true
            }
        ],
        "refund": null,
        "refunds": [],
        "currencyOptions": null,
        "flow": null
    }
}

{
    "source": "payment",
    "event": "statusChanged",
    "data": {
        "uuid": "02256fad-b607-41b9-8e05-676d33bf1739",
        "merchantDisplayName": "Merchant",
        "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
        "dateCreated": 1720779080000,
        "expiryDate": 1720779183517,
        "quoteExpiryDate": 1720779140000,
        "acceptanceExpiryDate": 1720779150000,
        "quoteStatus": "PENDING",
        "reference": "test_reference_out_WRXOVB",
        "type": "OUT",
        "subType": "merchantPayOut",
        "status": "EXPIRED",
        "displayCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 5,
            "actual": 0
        },
        "paidCurrency": {
            "currency": "ETH",
            "amount": 0.00169047,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0,
            "actual": 0
        },
        "networkFeeCurrency": {
            "currency": "ETH",
            "amount": 0.00035553,
            "actual": 0
        },
        "displayRate": {
            "base": "ETH",
            "counter": "EUR",
            "rate": 2957.757310097192
        },
        "exchangeRate": {
            "base": "EUR",
            "counter": "ETH",
            "rate": 0.000338094443
        },
        "address": null,
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=02256fad-b607-41b9-8e05-676d33bf1739",
        "transactions": [],
        "refund": null,
        "refunds": [],
        "currencyOptions": null,
        "flow": null
    }
}