Skip to main content

Track transactions

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

warning

If you use walletID in the payment 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 it will be discontinued soon.

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

EventDescription
statusChangedPayout has transitioned to a new state.
refundInitiatedRefund process has begun for a cryptocurrency payment.
transactionOnHoldPayment has been sent to a high risk address and is held to be further analyzed.

Payment status changed​

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",
            "network": "ETHEREUM",
            "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
    }
}

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",
                "network": "ETHEREUM",
                "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,
                    "network": "ETHEREUM",
                    "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
    }
}

Transaction on hold​

bvnk:payment:crypto:transaction-on-hold

{
  "event": "bvnk:payment:crypto:transaction-on-hold",
  "eventId": "01998078-3e41-7a64-92f2-d3c6f3713e95",
  "timestamp": "2025-09-25T10:43:07.969870Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "01998078-0eda-7794-a3aa-97566f9c04e0",
    "pegged": false,
    "refund": null,
    "status": "PROCESSING",
    "address": {
      "tag": null,
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x52a2cf95A494Cc7A39D9Cfa6ceF8fB43D1E3993e&uint256=7107892",
      "address": "0x52a2cf95A494Cc7A39D9Cfa6ceF8fB43D1E3993e",
      "network": "ETHEREUM",
      "alternatives": []
    },
    "refunds": [],
    "subType": "merchantPayOut",
    "twoStep": false,
    "metadata": {},
    "walletId": "a:24072237783989:Unkx9kW:1",
    "reference": "dc6d9706-020c-4a83-87db-0fbca9f11afd",
    "returnUrl": "",
    "customerId": "0e493702-f408-4a56-b842-603ac9058253",
    "expiryDate": 1758883376000,
    "merchantId": "19eda61c-aabc-4186-8ab1-46a3da181bb6",
    "dateCreated": 1758796976000,
    "displayRate": {
      "base": "USDC",
      "rate": 1.001703458634,
      "counter": "USD"
    },
    "feeCurrency": {
      "actual": 0,
      "amount": 0.07,
      "currency": "USD"
    },
    "quoteStatus": "ACCEPTED",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/01998078-0eda-7794-a3aa-97566f9c04e0",
    "exchangeRate": {
      "base": "USD",
      "rate": 0.998299489847,
      "counter": "USDC"
    },
    "paidCurrency": {
      "actual": 0,
      "amount": 7.107892,
      "currency": "USDC"
    },
    "transactions": [
      {
        "hash": null,
        "amount": 7.107892,
        "sources": [],
        "isOnHold": true,
        "network": "ETHEREUM",
        "dateCreated": 1758796988000,
        "displayRate": {
          "base": "USDC",
          "rate": 1.001703458634,
          "counter": "USD"
        },
        "exchangeRate": {
          "base": "USD",
          "rate": 0.9982994898469539,
          "counter": "USDC"
        },
        "dateConfirmed": null,
        "networkFeeAmount": 0,
        "networkFeeCurrency": "USDC"
      }
    ],
    "walletCurrency": {
      "actual": 7.12,
      "amount": 7.12,
      "currency": "USD"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 7.12,
      "currency": "USD"
    },
    "quoteExpiryDate": 1758800577000,
    "networkFeeCurrency": {
      "actual": 0,
      "amount": 1.76,
      "currency": "USD"
    },
    "merchantDisplayName": "USD Merchant",
    "acceptanceExpiryDate": 1758797007000,
    "embeddedCustomerDetails": {
      "reference": null,
      "externalReference": "givanov-airbnb-custom-ref123"
    }
  }
}

Webhook fields​

FieldDescription
eventType of the event triggering the webhook.
eventIdUnique identifier for the event.
timestampTimestamp of when the event occurred.
data.flowFlow type of the payment.
data.typeType of the payment event.
data.uuidUnique identifier for the payout transaction.
data.peggedWhether the payment is pegged.
data.refundRefund information for the payment.
data.statusStatus of the payout. Possible values:
• PENDING
• PROCESSING
• PENDING_APPROVAL
• ON_HOLD
• COMPLETED
• EXPIRED
• CANCELLED
• FAILED
• RETURNED
data.addressPayment address information.
data.address.addressThe actual payment address.
data.address.alternativesAlternative addresses for the payment.
data.address.networkNetwork of the payment address (e.g., ETHEREUM).
data.address.protocolProtocol of the payment address (e.g., ERC20).
data.address.tagTag associated with the payment address.
data.address.uriURI of the payment address.
data.refundsList of refunds associated with the payment.
data.subTypeSubtype of the payment (e.g., merchantPayOut, merchantRefund, merchantPayIn).
data.twoStepWhether the payment requires a two-step process.
data.metadataAdditional metadata associated with the webhook event.
data.referenceReference identifier for the payment.
data.returnUrlURL to return to after payment completion.
data.customerIdUnique identifier of the customer.
data.expiryDateExpiry date of the payment.
data.merchantIdUnique identifier of the merchant.
data.dateCreatedTimestamp when the payment was created.
data.displayRateDisplay rate information for the payment.
data.feeCurrencyFee currency information including amount and currency.
data.quoteStatusStatus of the quote (e.g., ACCEPTED, TEMPLATE).
data.redirectUrlURL to redirect to for payment processing.
data.exchangeRateExchange rate information for the payment.
data.paidCurrencyPaid currency information including amount and currency.
data.transactionsArray of transaction details.
data.transactions[].amountAmount of the transaction.
data.transactions[].dateConfirmedDate when the transaction was confirmed.
data.transactions[].dateCreatedDate when the transaction was created.
data.transactions[].displayRateDisplay rate for the transaction.
data.transactions[].exchangeRateExchange rate for the transaction.
data.transactions[].hashHash of the transaction.
data.transactions[].isOnHoldWhether the transaction is on hold.
data.transactions[].networkFeeAmountNetwork fee amount for the transaction.
data.transactions[].networkFeeCurrencyCurrency of the network fee.
data.transactions[].protocolProtocol of the transaction (e.g., ERC20).
data.transactions[].sourcesSource addresses for the transaction.
data.walletCurrencyWallet currency information including amount and currency.
data.currencyOptionsAvailable currency options for the payment.
data.displayCurrencyDisplay currency information including amount and currency.
data.quoteExpiryDateExpiry date of the quote.
data.networkFeeCurrencyNetwork fee currency information including amount and currency.
data.merchantDisplayNameDisplay name of the merchant.
data.acceptanceExpiryDateExpiry date for payment acceptance.
data.walletIdUnique identifier of the wallet.
data.embeddedCustomerDetailsEmbedded customer details including reference and external reference.
data.idUnique identifier for the payout transaction.
data.fees.customerFee.amountAmount of the customer fee.
data.fees.customerFee.currencyCurrency code of the customer fee.
data.fees.processingFee.amountAmount of the processing fee.
data.fees.processingFee.currencyCurrency code of the processing fee.
data.methodPayment method used for the payout. Possible values:
• CRYPTO (Only for crypto payouts. Not applicable to fiat)
• WALLET
• CARD (Only for crypto payouts. Not applicable to fiat)
• SEPA_CT
• SEPA_INST
• FASTER_PAYMENT
• SWIFT
• ACH
• ACH_SAME_DAY
• FEDWIRE
• FEDNOW
• RTP
• BOOK
• UNKNOWN
data.createdAtTimestamp when the payout was created.
data.directionDirection of the payment: incoming (IN) or outgoing (OUT).
data.updatedAtTimestamp when the payout was last updated.
data.originator.amountAmount sent by the originator.
data.originator.customerIdUnique identifier of the customer.
data.originator.currencyCurrency code of the originator amount.
data.originator.entity.legalNameLegal name of the sender entity.
data.originator.entity.typeType of the sender entity.
data.originator.walletIdWallet ID of the Originator.
data.beneficiary.amountAmount received by the Beneficiary.
data.beneficiary.currencyCurrency code of the beneficiary amount.
data.beneficiary.entity.address.addressLine1First line of the beneficiary's address.
data.beneficiary.entity.address.addressLine2Second line of the Beneficiary's address.
data.beneficiary.entity.address.cityCity of the Beneficiary's address.
data.beneficiary.entity.address.countryCountry code of the Beneficiary's address.
data.beneficiary.entity.address.postCodePostal code of the beneficiary's address.
data.beneficiary.entity.address.regionRegion/state of the beneficiary's address.
data.beneficiary.entity.dateOfBirthDate of birth of the beneficiary.
data.beneficiary.entity.firstNameFirst name of the beneficiary for individuals.
data.beneficiary.entity.lastNameLast name of the beneficiary for individuals.
data.beneficiary.entity.relationshipTypeRelationship type of the beneficiary.
data.beneficiary.entity.typeType of the beneficiary entity.
data.beneficiary.bankAccount.accountNumberAccount number of the beneficiary.
data.beneficiary.bankAccount.accountNumberFormatFormat of the account number of the beneficiary.
data.beneficiary.bankAccount.bank.address.addressLine1First line of the bank's address.
data.beneficiary.bankAccount.bank.address.addressLine2Second line of the bank's address.
data.beneficiary.bankAccount.bank.address.cityCity of the bank's address.
data.beneficiary.bankAccount.bank.address.countryCountry code of the bank's address.
data.beneficiary.bankAccount.bank.address.postCodePostal code of the bank's address.
data.beneficiary.bankAccount.bank.address.regionRegion/state of the bank's address.
data.beneficiary.bankAccount.bank.identificationCodeBank identification code (BIC/SWIFT).
data.beneficiary.bankAccount.bank.nidNational identifier of the beneficiary's bank.
data.beneficiary.bankAccount.intermediaryBanksList of intermediary banks involved in the transaction.
data.beneficiary.remittanceInformationAdditional information for the payment.
metadataAdditional metadata associated with the webhook event.
Was this page helpful?
Last updated on