⚠️ 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. When a deposit fails, Bridge needs to return the funds somewhere — but:

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.

❗️

Returning funds to the sender is not safe and not the default behavior. Bridge will not do this unless explicitly configured.

Best Practice: Use a Static Return Address

We recommend configuring a Bridge wallet or developer-controlled wallet as your crypto return destination.

{
  "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 Address Per Developer

As of now, you can only define one return policy for all transfers. This means:

• You cannot currently specify different return wallets for USDT and USDC.
• If you list a USDC-only wallet (e.g., a Circle wallet) and we need to refund USDT, the funds may be lost.

Unsupported Chains for Returns

Some chains are supported for deposits but not for refunds:

• Tron: We can receive USDT but cannot refund on Tron programmatically.
• Stellar: We do not support adding a memo when refunding. This may cause issues unless the recipient wallet auto-credits.

If you use these chains, we recommend:

• Using Ethereum as your refund chain for USDT.
• Avoiding Stellar unless you're confident that your wallet provider credits without memos (e.g., Airtm has confirmed this for their use case).

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.