⚠️ Set a Crypto Return Policy

If you're creating transactions that involve crypto deposits, it's critical to configure a crypto return policy. Without one, Bridge may be unable to safely return funds in the event of a failed transaction or refund — potentially resulting in lost customer funds.

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. 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.

✅ Recommended: Use 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.

Recommendations:

• Use Ethereum as the refund chain for USDT.
• Avoid using Stellar unless your wallet provider supports auto-crediting (e.g., Airtm has confirmed this works for them).

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.