Crypto Payouts

To configure Payout webhooks, go to the BVNK Portal and navigate to Integrations > Webhooks. For the full guide, see Create a Webhook Listener.

🚧
If you use walletID in the request that produces the webhook, note that you will also receive this field in the webhook response. In this case, you can ignore merchantID, since merchantId will be discontinued soon.

Crypto: status change

The bvnk:payment:crypto:status-change webhook is triggered when the status of the crypto transaction changes, for example, from Processing to Complete or Expired.

{
  "event": "bvnk:payment:crypto:status-change",
  "eventId": "019856c0-5fd6-79c4-8065-3fa5ea70aa3e",
  "timestamp": "2025-07-29T15:15:04.790711Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "96491bf1-5af6-4a42-9d35-6e623a9e3426",
    "pegged": false,
    "refund": null,
    "status": "PROCESSING",
    "address": {
      "tag": null,
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3A9EE18E76A9fCe8261B0CA33723&uint256=6E+6",
      "address": "0xa59d9f28537a3A9EE18E76A9fCe8261B0CA33723",
      "protocol": "ERC20",
      "alternatives": []
    },
    "refunds": [],
    "subType": "merchantPayOut",
    "twoStep": true,
    "metadata": {},
    "reference": "REF65908",
    "returnUrl": "",
    "customerId": "839ef707-91bb-44f5-b762-94a91310aaaa",
    "expiryDate": 1753888503000,
    "merchantId": "e91a7928-7353-4ad4-93eb-32632f01b7b6",
    "dateCreated": 1753802103000,
    "displayRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "feeCurrency": {
      "actual": 0,
      "amount": 1.729048,
      "currency": "USDC"
    },
    "quoteStatus": "ACCEPTED",
    "redirectUrl": "https://pay.bvnk.com/payout/96491bf1-5af6-4a42-9d35-6e623a9e3426",
    "exchangeRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "paidCurrency": {
      "actual": 0,
      "amount": 6,
      "currency": "USDC"
    },
    "transactions": [],
    "walletCurrency": {
      "actual": 6,
      "amount": 6,
      "currency": "USDC"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 6,
      "currency": "USDC"
    },
    "quoteExpiryDate": 1753805701000,
    "networkFeeCurrency": {
      "actual": 0,
      "amount": 0,
      "currency": "USDC"
    },
    "merchantDisplayName": "USDC",
    "acceptanceExpiryDate": 1753802131000
  }
}

{
  "event": "bvnk:payment:crypto:status-change",
  "eventId": "01983c01-6077-7282-a6c8-9b837847ff70",
  "timestamp": "2025-07-24T10:36:19.959993400Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "pegged": false,
    "refund": null,
    "status": "COMPLETE",
    "address": {
      "tag": null,
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723&uint256=5E+6",
      "address": "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723",
      "protocol": "ERC20",
      "alternatives": []
    },
    "refunds": [],
    "subType": "merchantRefund",
    "twoStep": false,
    "metadata": {},
    "reference": "RefundWebhook-318302166",
    "returnUrl": "",
    "customerId": "487548579",
    "expiryDate": 1761237313000,
    "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
    "dateCreated": 1753353313000,
    "displayRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "feeCurrency": {
      "actual": 5.003059,
      "amount": 5.003059,
      "currency": "USDC"
    },
    "quoteStatus": "ACCEPTED",
    "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "exchangeRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "paidCurrency": {
      "actual": 5,
      "amount": 5,
      "currency": "USDC"
    },
    "transactions": [
      {
        "hash": "0xd915f19f8505bc90199d88a5f04a412b12662d9ca10e14368d24d8b1e142028a",
        "amount": 5,
        "sources": [],
        "isOnHold": false,
        "protocol": "ERC20",
        "dateCreated": 1753353380000,
        "displayRate": {
          "base": "USDC",
          "rate": 1,
          "counter": "USDC"
        },
        "exchangeRate": {
          "base": "USDC",
          "rate": 1,
          "counter": "USDC"
        },
        "dateConfirmed": 1753353380000,
        "networkFeeAmount": 0,
        "networkFeeCurrency": "USDC"
      }
    ],
    "walletCurrency": {
      "actual": 5,
      "amount": 5,
      "currency": "USDC"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 5,
      "amount": 5,
      "currency": "USDC"
    },
    "quoteExpiryDate": 1761237313000,
    "networkFeeCurrency": {
      "actual": 0,
      "amount": 0,
      "currency": null
    },
    "merchantDisplayName": "Merch_arch",
    "acceptanceExpiryDate": 1753353343000
  }
}

{
  "event": "bvnk:payment:crypto:status-change",
  "eventId": "01983c00-5d18-7e5e-b85c-c51cf4d42105",
  "timestamp": "2025-07-24T10:35:13.560470800Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "pegged": false,
    "refund": {
      "flow": null,
      "type": "IN",
      "uuid": "f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
      "pegged": false,
      "refund": null,
      "status": "EXPIRED",
      "address": {
        "tag": null,
        "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x632cbf94b236419c63f23867a89f4beded3ee3da&uint256=2E+6",
        "address": "0x632cbf94b236419c63f23867a89f4beded3ee3da",
        "protocol": "ERC20",
        "alternatives": []
      },
      "refunds": [],
      "subType": "merchantPayIn",
      "twoStep": false,
      "metadata": {},
      "reference": "RefundWebhook",
      "returnUrl": "",
      "customerId": "234234234",
      "expiryDate": 1753350971000,
      "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
      "dateCreated": 1753350575000,
      "displayRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "feeCurrency": {
        "actual": 0,
        "amount": 0.014,
        "currency": "USDC"
      },
      "quoteStatus": "ACCEPTED",
      "redirectUrl": "https://pay.bvnk.com/payin/f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
      "exchangeRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "paidCurrency": {
        "actual": 5,
        "amount": 2,
        "currency": "USDC"
      },
      "transactions": [
        {
          "hash": "0x8c29b2b0c6d841b550783c797d3b9668675c05fb17d56db1c9d2172db2536d0e",
          "amount": 5,
          "sources": [
            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
          ],
          "isOnHold": false,
          "protocol": "ERC20",
          "dateCreated": 1753353196000,
          "displayRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "exchangeRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "dateConfirmed": 1753353312000,
          "networkFeeAmount": 0.00011,
          "networkFeeCurrency": "USDC"
        }
      ],
      "walletCurrency": {
        "actual": 0,
        "amount": 2,
        "currency": "USDC"
      },
      "currencyOptions": null,
      "displayCurrency": {
        "actual": 0,
        "amount": 2,
        "currency": "USDC"
      },
      "quoteExpiryDate": 1753350875000,
      "networkFeeCurrency": {
        "actual": 0,
        "amount": 0,
        "currency": null
      },
      "merchantDisplayName": "Merch_arch",
      "acceptanceExpiryDate": 1753350605000
    },
    "status": "PROCESSING",
    "address": {
      "tag": null,
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723&uint256=5E+6",
      "address": "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723",
      "protocol": "ERC20",
      "alternatives": []
    },
    "refunds": [],
    "subType": "merchantRefund",
    "twoStep": false,
    "metadata": {},
    "reference": "RefundWebhook-318302166",
    "returnUrl": "",
    "customerId": "234234234",
    "expiryDate": 1761237313318,
    "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
    "dateCreated": 1753353313000,
    "displayRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "feeCurrency": {
      "actual": 5.003059,
      "amount": 5.003059,
      "currency": "USDC"
    },
    "quoteStatus": "ACCEPTED",
    "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "exchangeRate": {
      "base": "USDC",
      "rate": 1,
      "counter": "USDC"
    },
    "paidCurrency": {
      "actual": 0,
      "amount": 5,
      "currency": "USDC"
    },
    "transactions": [],
    "walletCurrency": {
      "actual": 5,
      "amount": 5,
      "currency": "USDC"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 5,
      "currency": "USDC"
    },
    "quoteExpiryDate": 1761237313318,
    "networkFeeCurrency": null,
    "merchantDisplayName": "Merch_arch",
    "acceptanceExpiryDate": 1753353343353
  }
}

Crypto: refund initiated

The bvnk:payment:crypto:refund-initiated webhook notifies when a refund process has begun for a cryptocurrency payment. This can happen if your merchant settings are set to auto-refund under- and overpayments, or if a payment is made to an expired payment link.

{
  "event": "bvnk:payment:crypto:refund-initiated",
  "eventId": "01983bf0-c3eb-77b8-bda2-3a09d9bb1235",
  "timestamp": "2025-07-24T10:18:11.307235200Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "bf651b97-722f-400b-b96f-3e56fe182cfe",
    "pegged": false,
    "refund": {
      "flow": null,
      "type": "IN",
      "uuid": "ad5c2cfc-6ec3-4e51-96f1-03dfad8efc11",
      "pegged": false,
      "refund": null,
      "status": "COMPLETE",
      "address": {
        "tag": null,
        "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x27f9bfa4e6782671e9224c5debdf4350a28bc728&uint256=2E+6",
        "address": "0x27f9bfa4e6782671e9224c5debdf4350a28bc728",
        "protocol": "ERC20",
        "alternatives": []
      },
      "refunds": [],
      "subType": "merchantPayIn",
      "twoStep": false,
      "metadata": {},
      "reference": "RefundWebhook1",
      "returnUrl": "",
      "customerId": "234850085",
      "expiryDate": 1753352469000,
      "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
      "dateCreated": 1753352169000,
      "displayRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "feeCurrency": {
        "actual": 0.014,
        "amount": 0.014,
        "currency": "USDC"
      },
      "quoteStatus": "ACCEPTED",
      "redirectUrl": "https://pay.bvnk.com/payin/ad5c2cfc-6ec3-4e51-96f1-03dfad8efc11",
      "exchangeRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "paidCurrency": {
        "actual": 5,
        "amount": 2,
        "currency": "USDC"
      },
      "transactions": [
        {
          "hash": "0x7551bf6f17e2d354f21415bdc46234872d6cc9cce1f504259bb72326b9e53b34",
          "amount": 5,
          "sources": [
            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
          ],
          "isOnHold": false,
          "protocol": "ERC20",
          "dateCreated": 1753352226000,
          "displayRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "exchangeRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "dateConfirmed": 1753352291000,
          "networkFeeAmount": 0.000148,
          "networkFeeCurrency": "USDC"
        }
      ],
      "walletCurrency": {
        "actual": 2,
        "amount": 2,
        "currency": "USDC"
      },
      "currencyOptions": null,
      "displayCurrency": {
        "actual": 2,
        "amount": 2,
        "currency": "USDC"
      },
      "quoteExpiryDate": 1753352469000,
      "networkFeeCurrency": {
        "actual": 0,
        "amount": 0,
        "currency": null
      },
      "merchantDisplayName": "Merch_arch",
      "acceptanceExpiryDate": 1753352199000
    },
    "status": "PENDING",
    "address": null,
    "refunds": [],
    "subType": "merchantRefund",
    "twoStep": false,
    "metadata": {},
    "reference": "REFUND-RefundWebhook1-296593287",
    "returnUrl": "",
    "customerId": "487548579",
    "expiryDate": 1761236291296,
    "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
    "dateCreated": 1753352291000,
    "displayRate": null,
    "feeCurrency": {
      "actual": 5.003059,
      "amount": 5.003059,
      "currency": "USDC"
    },
    "quoteStatus": "TEMPLATE",
    "redirectUrl": "https://pay.bvnk.com/payout/bf651b97-722f-400b-b96f-3e56fe182cfe",
    "exchangeRate": null,
    "paidCurrency": {
      "actual": 0,
      "amount": 0,
      "currency": null
    },
    "transactions": [],
    "walletCurrency": {
      "actual": 0,
      "amount": 3,
      "currency": "USDC"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 3,
      "currency": "USDC"
    },
    "quoteExpiryDate": null,
    "networkFeeCurrency": null,
    "merchantDisplayName": "Merch_arch",
    "acceptanceExpiryDate": null
  }
}

{
  "event": "bvnk:payment:crypto:refund-initiated",
  "eventId": "01983c00-5c32-77c1-9cfe-984d7d2efa6a",
  "timestamp": "2025-07-24T10:35:13.330886600Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "pegged": false,
    "refund": {
      "flow": null,
      "type": "IN",
      "uuid": "f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
      "pegged": false,
      "refund": null,
      "status": "EXPIRED",
      "address": {
        "tag": null,
        "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x632cbf94b236419c63f23867a89f4beded3ee3da&uint256=2E+6",
        "address": "0x632cbf94b236419c63f23867a89f4beded3ee3da",
        "protocol": "ERC20",
        "alternatives": []
      },
      "refunds": [],
      "subType": "merchantPayIn",
      "twoStep": false,
      "metadata": {},
      "reference": "RefundWebhook",
      "returnUrl": "",
      "customerId": "487548579",
      "expiryDate": 1753350971000,
      "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
      "dateCreated": 1753350575000,
      "displayRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "feeCurrency": {
        "actual": 0,
        "amount": 0.014,
        "currency": "USDC"
      },
      "quoteStatus": "ACCEPTED",
      "redirectUrl": "https://pay.bvnk.com/payin/f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
      "exchangeRate": {
        "base": "USDC",
        "rate": 1,
        "counter": "USDC"
      },
      "paidCurrency": {
        "actual": 5,
        "amount": 2,
        "currency": "USDC"
      },
      "transactions": [
        {
          "hash": "0x8c29b2b0c6d841b550783c797d3b9668675c05fb17d56db1c9d2172db2536d0e",
          "amount": 5,
          "sources": [
            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
          ],
          "isOnHold": false,
          "protocol": "ERC20",
          "dateCreated": 1753353196000,
          "displayRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "exchangeRate": {
            "base": "USDC",
            "rate": 1,
            "counter": "USDC"
          },
          "dateConfirmed": 1753353312000,
          "networkFeeAmount": 0.00011,
          "networkFeeCurrency": "USDC"
        }
      ],
      "walletCurrency": {
        "actual": 0,
        "amount": 2,
        "currency": "USDC"
      },
      "currencyOptions": null,
      "displayCurrency": {
        "actual": 0,
        "amount": 2,
        "currency": "USDC"
      },
      "quoteExpiryDate": 1753350875000,
      "networkFeeCurrency": {
        "actual": 0,
        "amount": 0,
        "currency": null
      },
      "merchantDisplayName": "Merch_arch",
      "acceptanceExpiryDate": 1753350605000
    },
    "status": "PENDING",
    "address": null,
    "refunds": [],
    "subType": "merchantRefund",
    "twoStep": false,
    "metadata": {},
    "reference": "RefundWebhook-318302166",
    "returnUrl": "",
    "customerId": "487548579",
    "expiryDate": 1761237313318,
    "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
    "dateCreated": 1753353313000,
    "displayRate": null,
    "feeCurrency": {
      "actual": 5.003059,
      "amount": 5.003059,
      "currency": "USDC"
    },
    "quoteStatus": "TEMPLATE",
    "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
    "exchangeRate": null,
    "paidCurrency": {
      "actual": 0,
      "amount": 0,
      "currency": null
    },
    "transactions": [],
    "walletCurrency": {
      "actual": 0,
      "amount": 5,
      "currency": "USDC"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 5,
      "currency": "USDC"
    },
    "quoteExpiryDate": null,
    "networkFeeCurrency": null,
    "merchantDisplayName": "Merch_arch",
    "acceptanceExpiryDate": null
  }
}

Updated 7 days ago