Skip to main content

​
Returning fiat deposits (ACH, Wire, and SEPA)

If your customer previously onramped via ACH, Wire, or SEPA and you need to return those funds (for example, due to a recall, refund, or rejected activity), you can initiate a return by creating a new transfer via the Bridge API. This flow is supported only for returning fiat deposits and works across all orchestration products, including Transfers and Virtual Accounts.
Returns always send funds back to the original sender of the fiat deposit.
Example: Return funds using a crypto source 
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
  --header 'Api-Key: <API Key>' \
  --header 'Idempotency-Key: <Unique Idempotency Key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": "50.0",
    "on_behalf_of": "cust_alice",
    "source": {
      "payment_rail": "base",
      "currency": "usdc",
      "from_address": "0xdeadbeef"
    },
    "destination": {
      "payment_rail": "fiat_deposit_return",
      "currency": "usd",
      "deposit_id": "deposit_123"
    }
}'

​
How it Works

  • Bridge creates a transfer and returns source deposit instructions.
  • You send the exact amount of crypto to the provided address.
  • Once funded, Bridge initiates a fiat return to the original deposit sender.

​
Validations

When calling this endpoint, Bridge enforces the following rules:
ConstraintDescription
source.currencyMust be a supported crypto (e.g. usdc, usdb).
source.currency ↔ destination.currencyMust be equivalent (e.g. usdc → usd).
on_behalf_ofMust match the original deposit’s customer ID.
amountFor ACH returns, must match the original deposit amount. For Wire and SEPA, can be ≤ original amount.
Time windowReturns must be initiated within 60 days of the original deposit.
For automated or high-volume return flows, we strongly recommend using a Bridge wallet as the funding source. This allows you to pre-fund once and initiate returns programmatically without managing per-return on-chain transfers.
Request
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
  --header 'Api-Key: <API Key>' \
  --header 'Idempotency-Key: <Unique Idempotency Key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": "50.0",
    "on_behalf_of": "cust_alice",
    "source": {
      "payment_rail": "bridge_wallet",
      "currency": "usdb",
      "bridge_wallet_id": "the-wallet-uuid"
    },
    "destination": {
      "payment_rail": "fiat_deposit_return",
      "currency": "usd",
      "deposit_id": "deposit_123"
    }
}'
Why use a Bridge Wallet?
  • Simplifies automation of return flows
  • Avoids funding delays or incorrect on-chain transfers
  • Lets you pre-fund once and initiate returns programmatically
You can use your own wallet or the wallet belonging to your customer to fund the return.

​
Returning crypto deposits

​
How Bridge determines where to return crypto payments

When refunding crypto deposits, Bridge determines the return address in the following order:
  1. Bridge-originated funds If the transaction originated from a Bridge wallet or prefunded account, funds are returned to that same source.
  2. Liquidation Address drains If the deposit is associated with a Liquidation Address that has a return_address, Bridge returns funds there.
  3. Transfers with return instructions If the originating Transfer includes return_instructions.return_address, Bridge uses that address.
  4. Crypto return policy If none of the above apply, Bridge falls back to your configured crypto return policy.
  5. If Bridge still cannot determine a return address The payment will enter a missing_return_policy state.

​
Crypto return policy

For crypto deposits originating outside of Bridge, you can configure a crypto return policy to ensure failed or refunded payments can be safely returned. This policy exists because many exchanges use omnibus wallets, where returning funds to the sender may result in permanent loss.

​
When should you use a crypto return policy?

Use a crypto return policy when you want Bridge to always return crypto to a single, developer-controlled address (for example, your omnibus wallet). You can then handle customer-specific refunds off-chain or in your own systems from that wallet.

​
Why Is This Important?

Unlike fiat payments, crypto transactions are irreversible. If a crypto deposit fails, Bridge needs to know where to return the funds. You can configure one of two return strategies:
  • refund_to_sender — risky, not recommended.
  • static_address — a known, developer-controlled wallet.
Returning funds to the sender is not safe and not the default behavior.Bridge will not do this unless explicitly configured. Most exchanges use omnibus wallets that serve many users. Please note refund_to_sender is not a supported policy if you are building a stablecoin sandwich.Returning funds to an exchange wallet often leads to fund loss or lengthy recovery procedures. Stellar and Tron require memos to attribute funds to users — and without a correct memo, funds may be permanently untraceable.

​
Recommend using a static return address

We strongly recommend configuring a Bridge wallet or a developer-controlled wallet as the designated return address.
Example
{
  "crypto_return_policy": {
    "strategy": "static_address",
    "return_address": "0xYourWalletAddressHere",
    "payment_rail": "ethereum",
    "currency": "usdc"
  }
}
  • strategy: Set to static_address.
  • return_address: A wallet you own and control.
  • payment_rail: The blockchain the address belongs to (e.g., ethereum, solana).
  • currency: The expected refund asset.

​
Limitations and Edge Cases

One Return Address per Currency and Chain When using the static_address strategy, you can define only one return address per currency and chain combination.
  • For example, if you’ve configured a static_address for USDC on Ethereum, all USDC deposits on Ethereum will be refunded to that address.
  • If Bridge cannot find an exact match for the currency and chain (e.g., USDC on Base), we will fall back to a compatible address for the same currency on a different chain.
So if you’ve only set a return address for USDC × Ethereum, then USDC × Base deposits will also be returned to the Ethereum address.
This fallback behavior is best-effort and may not work in all cases — especially if the recipient wallet isn’t cross-chain compatible. When in doubt, explicitly define return addresses for each chain-currency pair you intend to support.
Unsupported Chains for Returns Some chains are supported for deposits but not for refunds.
ChainLimitation
TronWe can receive USDT, but cannot return funds via Tron. Instead, use Ethereum as the refund chain for USDT.

​
Daisy-Chained Transfers

Some developers break transfers into multi-step flows (e.g., USD → USDC → EUR):
  • If the final step fails (e.g., SEPA payout), the funds may be refunded to the wrong wallet, such as an internal hot wallet from a previous step.
  • This may result in stuck funds that are not attributable to an end-user.
Recommendation: Use Bridge wallets for all intermediate steps and refund paths to ensure full traceability.