> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# transactionTransfer.completed

<Update label="v1.1.0" description="minor update">
  ### refundReason field added

  Refunded transfers now say why they were refunded.

  | Field                   | Type                | Description                                                                                                                                                                                                 |
  | ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `transfer.refundReason` | `string` (optional) | Why the transfer was refunded: `limit_exceeded`, `invalid_destination`, `returned_by_bank`, `expired`, `amount_mismatch`, or `other`. Present only on refunded transfers, and some refunds carry no reason. |
</Update>

<Update label="v1.0.0" description="initial release">
  ### transactionTransfer.completed

  Added the `transactionTransfer` webhook with action `completed` for transfer transactions. Rain triggers this webhook when a transfer settles.

  #### Payload Fields

  | Field                               | Type                | Description                                                                                                                |
  | ----------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
  | `id`                                | `string`            | The transaction ID                                                                                                         |
  | `type`                              | `string`            | Always `transfer` for this webhook                                                                                         |
  | `transfer.userId`                   | `string` (optional) | The user ID for consumer accounts                                                                                          |
  | `transfer.companyId`                | `string` (optional) | The company ID for corporate accounts                                                                                      |
  | `transfer.source.amount`            | `string`            | Source amount as a decimal string (e.g., `"100.00"`)                                                                       |
  | `transfer.source.currency`          | `string`            | Source currency code                                                                                                       |
  | `transfer.source.rail`              | `string`            | Source rail (e.g., `onchain`, `wire`)                                                                                      |
  | `transfer.source.referenceId`       | `string` (optional) | Source reference ID                                                                                                        |
  | `transfer.source.address`           | `object` (optional) | Source address (see address types below)                                                                                   |
  | `transfer.destination.amount`       | `string` (optional) | Destination amount as a decimal string                                                                                     |
  | `transfer.destination.currency`     | `string`            | Destination currency code                                                                                                  |
  | `transfer.destination.rail`         | `string`            | Destination rail                                                                                                           |
  | `transfer.destination.referenceId`  | `string` (optional) | Destination reference ID                                                                                                   |
  | `transfer.destination.address`      | `object` (optional) | Destination address (see address types below)                                                                              |
  | `transfer.depositAddress`           | `object` (optional) | Deposit address for the transfer (see deposit address types below)                                                         |
  | `transfer.fees.rain.currency`       | `string`            | Currency of Rain's fee                                                                                                     |
  | `transfer.fees.rain.amount`         | `string`            | Rain's fee amount as a decimal string                                                                                      |
  | `transfer.fees.rain.amountUSD`      | `string`            | Rain's fee amount in USD as a decimal string                                                                               |
  | `transfer.fees.developer.currency`  | `string`            | Currency of the developer fee                                                                                              |
  | `transfer.fees.developer.amount`    | `string`            | Developer fee amount as a decimal string                                                                                   |
  | `transfer.fees.developer.amountUSD` | `string`            | Developer fee amount in USD as a decimal string                                                                            |
  | `transfer.exchangeRate`             | `number` (optional) | Exchange rate applied                                                                                                      |
  | `transfer.status`                   | `string`            | Transfer status (`pending`, `awaiting_transfer`, `processing`, `settled`, `failed`, `cancelled`, `expired`, or `refunded`) |
  | `transfer.createdAt`                | `string`            | ISO 8601 timestamp of creation                                                                                             |
  | `transfer.updatedAt`                | `string`            | ISO 8601 timestamp of last update                                                                                          |
  | `transfer.quoteId`                  | `string`            | The quote ID this transfer was created from                                                                                |
  | `transfer.expiresAt`                | `string`            | ISO 8601 timestamp of when the transfer expires                                                                            |

  #### Address Types

  Source and destination addresses can be one of:

  **Onchain address:**

  | Field     | Type     | Description      |
  | --------- | -------- | ---------------- |
  | `type`    | `string` | Always `onchain` |
  | `address` | `string` | Wallet address   |

  **Payment account address:**

  | Field  | Type     | Description             |
  | ------ | -------- | ----------------------- |
  | `type` | `string` | Always `paymentAccount` |
  | `id`   | `string` | Payment account ID      |

  #### Deposit Address Types

  The deposit address can be one of:

  **Fiat deposit address:**

  | Field                    | Type                | Description           |
  | ------------------------ | ------------------- | --------------------- |
  | `type`                   | `string`            | Always `fiat`         |
  | `beneficiaryName`        | `string`            | Beneficiary name      |
  | `beneficiaryAddress`     | `string`            | Beneficiary address   |
  | `beneficiaryBankName`    | `string`            | Bank name             |
  | `beneficiaryBankAddress` | `string`            | Bank address          |
  | `accountNumber`          | `string`            | Account number        |
  | `routingNumber`          | `string`            | Routing number        |
  | `transferMessage`        | `string` (optional) | Transfer message/memo |

  **Onchain deposit address:**

  | Field     | Type     | Description      |
  | --------- | -------- | ---------------- |
  | `type`    | `string` | Always `onchain` |
  | `address` | `string` | Wallet address   |

  #### Transfer Status Values

  | Status       | Description                              |
  | ------------ | ---------------------------------------- |
  | `pending`    | Transfer has been initiated              |
  | `processing` | Transfer is being processed              |
  | `settled`    | Transfer has been completed successfully |
  | `failed`     | Transfer has failed                      |
  | `refunded`   | Transfer was refunded                    |

  #### Example Payload

  ```json theme={null}
  {
      "resource": "transactionTransfer",
      "action": "completed",
      "version": "1.0.0",
      "body": {
          "id": "txn_abc123",
          "type": "transfer",
          "transfer": {
              "companyId": "cmp_456abc",
              "source": {
                  "amount": "1000.00",
                  "currency": "usdc",
                  "rail": "onchain",
                  "referenceId": "ref_123",
                  "address": {
                      "type": "onchain",
                      "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
              },
              "destination": {
                  "amount": "998.50",
                  "currency": "usd",
                  "rail": "wire",
                  "referenceId": "ref_456",
                  "address": {
                      "type": "paymentAccount",
                      "id": "pa_456def"
                  }
              },
              "depositAddress": {
                  "type": "fiat",
                  "beneficiaryName": "Rain Financial Inc.",
                  "beneficiaryAddress": "123 Main St, New York, NY",
                  "beneficiaryBankName": "Example Bank",
                  "beneficiaryBankAddress": "456 Bank Ave, New York, NY",
                  "accountNumber": "1234567890",
                  "routingNumber": "021000021"
              },
              "fees": {
                  "rain": {
                      "currency": "usd",
                      "amount": "1.00",
                      "amountUSD": "1.00"
                  },
                  "developer": {
                      "currency": "usd",
                      "amount": "0.50",
                      "amountUSD": "0.50"
                  }
              },
              "exchangeRate": 1.0,
              "status": "settled",
              "createdAt": "2026-01-27T15:30:00.000Z",
              "updatedAt": "2026-01-27T16:45:00.000Z",
              "quoteId": "355e0a5c-76a5-4d13-bcee-f2ad39abe710",
              "expiresAt": "2026-01-28T15:30:00.000Z"
          }
      }
  }
  ```
</Update>