transactionTransfer.completed

​

v1.1.0

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.

​

v1.0.0

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

{
    "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"
        }
    }
}