Refund Reasons

Why a transfer gets refunded and what each refundReason value means.

When Rain returns a transfer’s funds to the sender, the transfer moves to the refunded status and carries a refundReason. This applies to every transfer: those you create with quotes and transfers, and those Rain creates when funds arrive on an onramp or offramp payment route. Use this page to understand what each reason means.

Where you see the refund reason

Rain returns refundReason on the transfer object, with the same values for every transfer type. You can read it in two places:

• The Transactions API. Filter by type=transfer to see transfers.
• The transactionTransfer webhooks (created, updated, and completed). The reason is in transfer.refundReason, and requires webhook version 1.1.0 or later. See the transfer object reference for the full payload.

refundReason is omitted on transfers that haven’t been refunded. Rain can set it shortly before the status changes to refunded, while the return is in progress.

{
  "status": "refunded",
  "refundReason": "invalid_destination"
}

Refund reasons

Reason	Meaning
limit_exceeded	The transfer went over a limit that applies to your program.
invalid_destination	The destination couldn’t receive the funds.
returned_by_bank	The destination bank sent the funds back after Rain submitted the payment.
expired	The transfer expired before it could complete.
amount_mismatch	The amount Rain received didn’t match the amount on the transfer.
other	Rain returned the funds for another reason.

Handle refunds in your integration

1. Listen for the webhook

   Subscribe to the transactionTransfer webhooks. A refunded transfer arrives with status set to refunded.

2. Read the reason

   Read transfer.refundReason and branch on it. Handle other as a catch-all.

3. Tell your user

   Show your user a clear message and, where it makes sense, prompt them to create a new transfer.

What’s next

Transfers

Learn how transfers move funds and which statuses they pass through.

Money Movement Limits

Check the limits and settlement times for each rail.