Auto-refund to source address

When a payment exception (overpayment, underpayment, or late payment) occurs, BVNK can automatically refund the cryptocurrency directly to the wallet address that sent the original payment. Unlike the standard refund flow where a payout link is generated, refund to source address requires no action from you or your customers.

note

Contact your account manager to enable refund to source address for your account.

How it works

When enabled, BVNK detects the originating wallet address from the incoming transaction and sends the refund directly to that address. No payout link is generated, and no further interaction is required.

You can configure which exception scenarios trigger a refund to the source address:

Overpayments: the overpaid amount is refunded.
Underpayments: the full payment amount is refunded.
Late payments: the full payment amount is refunded.

Each scenario can be enabled independently in your wallet settings, allowing you to control when automatic refunds are processed.

This feature offers the following benefits:

Faster refunds: customers receive refunds more quickly, enhancing their overall experience.
Reduced manual effort: automates the refund process for partners and their customers.
Improved efficiency: streamlines operations and reduces the risk of human error in refund processing.

Payments from centralised exchanges

If a payment originates from a centralised exchange, such as Coinbase, the refund is sent to the exchange's pooled account rather than the individual user's account. Partners or their customers must provide the refund transaction hash to the exchange to claim their funds.

Payments from self-hosted wallets

If a payment originates from a self-hosted wallet, the refunded amount appears immediately in the original wallet with no further action required.

Supported currencies

Refunds to the source address are supported for the following currencies:

ETH
USDT
USDC
BNB
PYUSD
XRP
SOL
POL
TRX

warning

Bitcoin (BTC) and other UTXO-based currencies are not supported. UTXO-based blockchains allow multiple transaction inputs, which makes it impossible to determine a single source address. Payments in unsupported currencies follow the standard refund flow using a payout link.

Webhooks

When a payment exception triggers a refund to the source address, you receive the following webhooks.

Payment exception webhook

You receive a webhook for the payment exception itself. For example, a transactionLate event for a late payment:

transactionLate webhook
{
  "source": "payment",
  "event": "transactionLate",
  "data": {
    "uuid": "3d8ff99f-3f68-4abb-980c-4c573f5fa96f",
    "merchantDisplayName": "MS USD wallet",
    "merchantId": "5bb854c2-3191-4534-9147-a38c85bc9c9c",
    "dateCreated": 1748856479000,
    "expiryDate": 1748856727000,
    "reference": "ETHautoRefund",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "EXPIRED",
    "displayCurrency": {
      "currency": "USD",
      "amount": 10,
      "actual": 0
    },
    "walletCurrency": {
      "currency": "USD",
      "amount": 10,
      "actual": 0
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.00402485,
      "actual": 0.00402485
    },
    "address": {
      "address": "0x3c972d5e50663a6a3f7a9449384b853684d6342a",
      "tag": null,
      "protocol": "ETH",
      "uri": "ethereum:0x3c972d5e50663a6a3f7a9449384b853684d6342a?value=4.02485E+15",
      "alternatives": []
    },
    "transactions": [
      {
        "dateCreated": 1748857852000,
        "dateConfirmed": 1748857936000,
        "hash": "0x48b6b6a433bead87974e6b5987dfaa5368bf8d48fdffc56cbbd66bb2d241f52c",
        "amount": 0.00402485,
        "networkFeeCurrency": "ETH",
        "networkFeeAmount": 0.00006932,
        "sources": [
          "0xa5f0e3bbfa02f58ac1b475d79e828dd8ad2226c7"
        ]
      }
    ]
  }
}

Note the transactions[].sources array. This contains the originating wallet address to which the refund will be sent.

Refund webhook

Next, you receive a refundInitiated event for the auto-refund. The address field contains the originating wallet address, and the status is COMPLETE once the refund has been processed:

refundInitiated webhook
{
  "source": "payment",
  "event": "refundInitiated",
  "data": {
    "uuid": "9f0a0195-58f0-46d4-9238-afbefed37136",
    "merchantDisplayName": "MS USD wallet",
    "merchantId": "5bb854c2-3191-4534-9147-a38c85bc9c9c",
    "dateCreated": 1748857937000,
    "reference": "REFUND-ETHautoRefund-916118588",
    "type": "OUT",
    "subType": "merchantRefund",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "USD",
      "amount": 9.98,
      "actual": 9.98
    },
    "walletCurrency": {
      "currency": "ETH",
      "amount": 0.00402485,
      "actual": 0.00402485
    },
    "paidCurrency": {
      "currency": "ETH",
      "amount": 0.00402485,
      "actual": 0.00402485
    },
    "address": {
      "address": "0xa5f0e3bbfa02f58ac1b475d79e828dd8ad2226c7",
      "tag": null,
      "protocol": "ETH",
      "uri": "ethereum:0xa5f0e3bbfa02f58ac1b475d79e828dd8ad2226c7?value=4.02485E+15",
      "alternatives": []
    },
    "transactions": [
      {
        "dateCreated": 1748858015000,
        "dateConfirmed": 1748858015000,
        "hash": "0x8a86c9d862865263aa213d5f9e3293fb7689bade803e633b875f77cd9dee09fd",
        "amount": 0.00402485
      }
    ]
  }
}

The reference field follows the pattern REFUND-{originalReference}-{id} and links the refund to the original payment.

For more details on refund webhooks, see the Refund webhook reference.

How it works​

Payments from centralised exchanges​

Payments from self-hosted wallets​

Supported currencies​

Webhooks​

Payment exception webhook​

Refund webhook​