Handling Refunds

How refunds flow through the card network, how Rain credits funds back, and how on-chain refunds return value to a user’s wallet or contract.

When a cardholder requests a refund from a merchant, the refund flows through the card network before reaching Rain. How Rain credits the funds back depends on your program type.

How refunds work

A refund occurs when a merchant agrees to return funds to a cardholder after a completed transaction. Unlike reversals, which cancel pending authorizations, refunds apply to transactions that have already settled.

The refund process follows these steps:

1. The cardholder requests a refund from the merchant.
2. The merchant settles the refund with Visa.
3. Visa subtracts the refund amount from the merchant’s Net Settlement Balance.
4. Rain receives the refund notification and issues a Credit Voucher.
5. Rain applies the Credit Voucher to the appropriate ledger balance.

Refund timing

Refunds generally complete within 30 business days of the merchant processing them, and refunds for canceled orders can take up to 30 business days after the pending charge clears. A merchant refund that stays pending for more than 10 days may have failed; if a refund exceeds 30 business days, escalate to Rain support with the transaction ID and the card’s last 4 digits.

Rain never credits a refund the merchant declined. The user must ask the merchant to retry the refund.

Credit Voucher distribution

When Rain receives a refund from the card network, it issues a Credit Voucher to restore the funds. Where Rain applies the credit depends on your program type.

Rain-managed programs

For Rain-managed programs, Rain handles the ledger on behalf of your users. When Rain processes a refund, it issues the Credit Voucher directly to the user’s ledger balance. The user’s available balance increases by the refund amount, and you receive a transaction.completed webhook with a negative amount indicating the credit.

For example, if a user receives a $50 refund, their ledger balance increases by $50 and you receive a webhook showing -5000 (in cents).

Partner-managed programs

For Partner-managed programs, you manage your own ledger and authorization decisions. When Rain processes a refund, it issues the Credit Voucher to your tenant’s ledger balance rather than to individual user balances. You are responsible for crediting the appropriate user on your own ledger after receiving the transaction.completed webhook.

For example, if one of your users receives a $50 refund, your tenant balance increases by $50. You then post the refund to your internal ledger and credit the user accordingly.

Do not credit refunds to users until you receive the transaction.completed webhook. Refunds may take several days to process through the card network.

Identifying refunds

Refunds appear as transactions with negative amounts. You can identify a refund by checking for:

• A negative amount value in the webhook payload.
• The spend transaction type.

Refunds may not always reference the original transaction ID, as merchants can process refunds independently. Use the merchant name and amount to match refunds to their original transactions when needed.

On-chain refunds

With onchain refunds enabled, in most cases your users receive refunds as on-chain stablecoin transfers instead of spending credit — the default, where an instant ledger credit grows a user’s spending power. Onchain refunds return stablecoins from a Rain-operated refund wallet to the user on-chain, so the refunded amount is withdrawable like their original funds.

How on-chain refunds work

You don’t need to take any action once Rain enables onchain refunds for your tenant: qualifying refunds settle on-chain automatically. Three events trigger an onchain refund:

• Processor refunds — a merchant-initiated refund that settles after the original transaction.
• Real Time Funding reversals — an authorization reversal on a tenant using Real Time Funding, where the excess collateral must return to the user’s source wallet.
• Accepted dispute reimbursements — the reimbursement for an accepted dispute, returned to the user on-chain instead of the account credit Rain would otherwise issue.

Once the transfer settles on-chain, you can track it through the transaction record and a webhook. Rain funds the transfer from a dedicated refund wallet.

Refund amount limits

An onchain refund can never exceed the amount of the original transaction it refunds. Rain caps each refund at the transaction’s remaining refundable amount — the original purchase amount minus any refunds already issued or still processing against that transaction.

When a refund request would exceed the remaining refundable amount, Rain reduces it to that amount and settles the reduced amount on-chain. The refund amount shown on the transaction record and in the onchainRefund.created and onchainRefund.completed webhooks reflects this reduced amount, so it may be smaller than the amount originally requested. For example, on a $100 purchase that already has $70 in refunds, a later $50 request settles as a $30 refund, the amount still remaining.

When earlier refunds already cover a transaction’s full amount, it has no remaining refundable amount, and Rain does not issue an onchain refund for it. Because Rain creates no refund, you receive no onchainRefund.created or onchainRefund.completed webhook for that request.

A reduced amount or a missing webhook is expected when a transaction is partially or fully refunded, not an error — see Webhook notifications or Identifying onchain refunds to confirm what settled.

Refund destinations

Where the funds land depends on how your tenant sources collateral:

Tenant model	Refund destination
Standard (collateral)	The user’s collateral contract on the refund chain
Real Time Funding	The wallet that originally funded the transaction

Enabling onchain refunds

You don’t toggle onchain refunds yourself — Rain enables them per tenant. If you use Real Time Funding, you get onchain refunds by default, since those users expect funds back in their own wallet.

Contact your Rain representative to enable onchain refunds for your tenant.

Supported chains and assets

Rain pays onchain refunds in USDC on every chain except Plasma, where it pays them in USDT0 (Plasma has no USDC deployment).

Collateral refunds

Refunds to a collateral contract can settle on any of the chains below. The chain used for a given refund depends on the refund routing available to your tenant at the time.

Chain	Sandbox	Production
Ethereum	Ethereum Sepolia (11155111 / 0xaa36a7)	Ethereum Mainnet (1 / 0x1)
Arbitrum	Arbitrum Sepolia (421614 / 0x66eee)	Arbitrum Mainnet (42161 / 0xa4b1)
Base	Base Sepolia (84532 / 0x14a34)	Base Mainnet (8453 / 0x2105)
Optimism	Optimism Sepolia (11155420 / 0xaa37dc)	Optimism Mainnet (10 / 0xa)
Polygon	Polygon Amoy (80002 / 0x13882)	Polygon Mainnet (137 / 0x89)
Avalanche	Avalanche Fuji (43113 / 0xa869)	Avalanche Mainnet (43114 / 0xa86a)
Plasma	Plasma Testnet (9746 / 0x2612)	Plasma Mainnet (9745 / 0x2611)

Real Time Funding refunds

Real Time Funding refunds return funds to the wallet that originally funded the transaction, so they settle on the chains Real Time Funding supports and require the user to have a wallet address on that chain.

Chain	Sandbox	Production
Arbitrum	Arbitrum Sepolia (421614 / 0x66eee)	Arbitrum Mainnet (42161 / 0xa4b1)
Base	Base Sepolia (84532 / 0x14a34)	Base Mainnet (8453 / 0x2105)
Plasma	Plasma Testnet (9746 / 0x2612)	Plasma Mainnet (9745 / 0x2611)

For USDC and USDT0 token addresses, see Real Time Funding → Supported Assets.

Identifying onchain refunds

When you fetch transactions, the response includes two fields that tell you how Rain processed a refund:

Field	Description
refundMethod	onchain_refund for an on-chain transfer, or spending_credit for a ledger credit
referenceInfo	Present once the on-chain transfer settles: reference is the transaction hash, rail is the chain ID

{
  "id": "9b1c3e44-2f0a-4c7e-8a1d-5e6f7a8b9c0d",
  "refundMethod": "onchain_refund",
  "referenceInfo": {
    "reference": "0x4f8a1c2b3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8",
    "rail": "0x2105"
  }
}

referenceInfo appears only after the on-chain transfer settles. Until then, the transaction shows refundMethod: onchain_refund without a reference.

Webhook notifications

To track a refund through its lifecycle, listen for the dedicated onchainRefund webhooks. You receive these events if you have onchain refunds or Real Time Funding enabled.

Webhook	When Rain sends it
onchainRefund.created	Rain creates the refund and begins processing it. The refund starts in PENDING status.
onchainRefund.completed	The on-chain transfer settles and the funds reach their destination.

Each event includes the refund amount, asset, chainId, and destinationKind, along with the transactionId of the refund transaction. Use destinationKind to tell where the funds land: AUTHPULL_SOURCE returns funds to the cardholder’s source wallet, and COLLATERAL_CONTRACT returns them to the collateral contract.

You can also confirm a refund from the transaction record itself — see Identifying onchain refunds.

What’s next

Refund transaction

Sample webhook payload for a refund transaction.

Settlement (Rain-managed)

How refunds settle in Rain-managed programs.

Settlement (Partner-managed)

How refunds settle in Partner-managed programs.