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. |
initial release
transactionTransfer.created
Added thetransactionTransfer webhook with action created for transfer transactions. Rain triggers this webhook when you initiate a new transfer.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 |
| 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 |
| Field | Type | Description |
|---|---|---|
type | string | Always onchain |
address | string | Wallet address |
Example Payload
{
"resource": "transactionTransfer",
"action": "created",
"version": "1.0.0",
"body": {
"id": "txn_abc123",
"type": "transfer",
"transfer": {
"userId": "usr_789xyz",
"source": {
"amount": "1000.00",
"currency": "usdc",
"rail": "onchain",
"address": {
"type": "onchain",
"address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"destination": {
"amount": "998.50",
"currency": "usd",
"rail": "wire",
"address": {
"type": "paymentAccount",
"id": "pa_456def"
}
},
"fees": {
"rain": {
"currency": "usd",
"amount": "1.00",
"amountUSD": "1.00"
},
"developer": {
"currency": "usd",
"amount": "0.50",
"amountUSD": "0.50"
}
},
"exchangeRate": 1.0,
"status": "pending",
"createdAt": "2026-01-27T15:30:00.000Z",
"updatedAt": "2026-01-27T15:30:00.000Z",
"quoteId": "355e0a5c-76a5-4d13-bcee-f2ad39abe710",
"expiresAt": "2026-01-28T15:30:00.000Z"
}
}
}