Transaction Events

Transaction webhooks notify your systems as money moves across spend, collateral, and payment activity (transaction events) and transfers (transactionTransfer events). Use them to reconcile activity and trigger workflows in real time, without polling the API. The following events are available:

Event	Description
`transaction.requested`	A cardholder attempts to authorize a purchase (spend).
`transaction.created`	Rain creates a spend, collateral, or payment transaction.
`transaction.updated`	A transaction changes, such as an incremental authorization or refund.
`transaction.completed`	A spend or payment transaction reaches a final, settled state.
`transactionTransfer.created`	You initiate a transfer.
`transactionTransfer.updated`	A transfer changes state.
`transactionTransfer.completed`	A transfer settles at the destination.

The two resources report amounts differently, so do not assume one convention across both. Every spend amount is an integer in cents: 5000 means $50.00. Every transactionTransfer amount is a decimal string in the currency’s major unit: "1000.00" means $1,000.00. Collateral amounts follow the asset and can include decimals for native token amounts.

Spend transaction webhooks include an optional eventReceivedAt timestamp field. This field captures when Rain first received the event from the payment processor, which can help with debugging timing issues and building audit trails.By default, this field is excluded from webhook payloads. Contact your Rain account manager to enable it for your tenant.

A single authorization moves through several states rather than firing once, and each state change is its own transaction.* event. The transaction.created event also covers payment and collateral transactions, while transaction.completed also covers payments. The body distinguishes the type.

Webhook Rain sends youYour handler (ack 2xx)Action / API callCard networkConditional stepException (dispute)

`transaction.requested`

Rain sends this webhook when an authorization request comes in for a transaction, such as a new purchase or an incremental authorization on an existing transaction.

`spend`

Rain triggers the spend webhook when a cardholder spends their card. Partner-managed programs need to put a hold on the collateral balance and respond to this webhook to authorize the transaction. You do not need to persist this information.

Payload

{
    "resource": "transaction",
    "action": "requested",
    "version": "1.1.0",
    "body": {
        "id": "txn_abc123",
        "type": "spend",
        "spend": {
            "amount": 7500,
            "currency": "usd",
            "localAmount": 6750,
            "localCurrency": "EUR",
            "authorizedAmount": 2500,
            "previouslyAuthorizedAmount": 5000,
            "merchantName": "HOTEL MARRIOTT",
            "merchantCity": "New York",
            "merchantCountry": "US",
            "merchantCategory": "Hotels and Motels",
            "merchantCategoryCode": "7011",
            "cardId": "card_123",
            "cardType": "virtual",
            "companyId": "company_456",
            "userId": "user_789",
            "userFirstName": "John",
            "userLastName": "Doe",
            "userEmail": "john.doe@example.com",
            "status": "pending",
            "authorizedAt": "2026-01-27T15:30:00.000Z",
            "exchangeRate": 1.11
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `spend` for this webhook
`spend.amount`	`number`	Transaction amount in USD cents
`spend.currency`	`string`	Currency code (for example, `usd`)
`spend.localAmount`	`number` (optional)	Transaction amount in local currency
`spend.localCurrency`	`string` (optional)	Local currency code
`spend.authorizedAmount`	`number`	The requested authorization amount
`spend.authorizationMethod`	`string` (optional)	Method of authorization
`spend.previouslyAuthorizedAmount`	`number`	The amount that was previously authorized
`spend.tokenizedSource`	`string` (optional)	Source of tokenization (for example, `apple_pay`, `google_pay`)
`spend.merchantName`	`string`	Merchant name
`spend.merchantCity`	`string`	Merchant city
`spend.merchantCountry`	`string`	Merchant country
`spend.merchantCategory`	`string`	Merchant category description
`spend.merchantCategoryCode`	`string`	Merchant category code (MCC)
`spend.merchantId`	`string` (optional)	Merchant ID
`spend.cardId`	`string`	The card ID used for the transaction
`spend.cardType`	`string`	The card type (`virtual` or `physical`)
`spend.companyId`	`string` (optional)	Company ID (for corporate cards)
`spend.userId`	`string`	The user ID
`spend.userFirstName`	`string`	User’s first name
`spend.userLastName`	`string` (optional)	User’s last name
`spend.userEmail`	`string`	User’s email
`spend.status`	`string`	Always `pending` for this webhook
`spend.authorizedAt`	`string`	ISO 8601 timestamp of authorization
`spend.signature`	`string` (optional)	Signature for verification
`spend.timestamp`	`number` (optional)	Unix timestamp
`spend.exchangeRate`	`number` (optional)	Exchange rate applied
`spend.iso8583.de41`	`string` (optional)	Terminal ID (ISO 8583 Data Element 41)
`spend.threeDSecure`	`boolean` (optional)	Indicates whether 3D Secure authentication was used for the transaction

Response

Limited availability:Only Partner-managed programs can authorize or reject transactions. Rain-managed programs do not support this feature at this time.

Respond with 200 OK (or any 2xx) to approve the transaction.
Respond with any non-2xx status code to reject it.

You can return a JSON body to confirm the decision and, when declining, include a rejection code:

{
  "success": true
}

{
  "success": false,
  "rejectionCode": "INSUFFICIENT_FUNDS"
}

The rejectionCode must be one of these exact values; anything else is recorded as UNKNOWN:

Value	Meaning
`INSUFFICIENT_FUNDS`	The user doesn’t have the funds for this authorization
`SUSPICIOUS_TRANSACTION`	You suspect fraud
`NOT_PERMITTED`	The transaction violates your program’s rules
`UNKNOWN`	Any other reason

`transaction.created`

Rain sends this webhook whenever it creates a transaction.

`collateral`

Rain sends the collateral webhook when a user or company adds collateral to their contract. For standard collateral contracts, these transactions are final, and Rain does not send an additional completed webhook. For payment-type contracts (where Rain treats deposits as payments rather than collateral backing), Rain also sends a transaction.completed webhook with type: "payment" when the deposit posts. Contact your Rain account manager to determine your contract configuration.

Payload

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resource": "transaction",
    "action": "created",
    "version": "1.1.0",
    "body": {
        "id": "txn_abc123",
        "type": "collateral",
        "collateral": {
            "amount": 100000,
            "currency": "usdc",
            "chainId": 1,
            "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
            "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
            "companyId": "company_456",
            "postedAt": "2026-01-27T15:30:00.000Z",
            "contractAddress": "0x9876543210fedcba9876543210fedcba98765432"
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `collateral` for this webhook
`collateral.amount`	`number`	Collateral amount (may include decimals for native token amounts)
`collateral.currency`	`string`	Asset name in lowercase (for example, `usdc`, `usdt`)
`collateral.chainId`	`number`	Blockchain chain ID (for example, `1` for Ethereum mainnet)
`collateral.walletAddress`	`string`	Wallet address the collateral was sent from
`collateral.transactionHash`	`string`	On-chain transaction hash
`collateral.companyId`	`string` (optional)	Company ID (for corporate accounts)
`collateral.userId`	`string` (optional)	User ID (for consumer accounts)
`collateral.postedAt`	`string`	ISO 8601 timestamp when the collateral was posted on-chain
`collateral.contractAddress`	`string`	The collateral contract address holding the funds

`spend`

Rain sends the spend webhook when it creates a transaction, whether the network authorizes or declines it. You must persist this information.

Payload

{
    "resource": "transaction",
    "action": "created",
    "version": "1.2.0",
    "body": {
        "id": "txn_abc123",
        "type": "spend",
        "spend": {
            "amount": 5000,
            "currency": "usd",
            "localAmount": 4500,
            "localCurrency": "EUR",
            "authorizedAmount": 5000,
            "merchantName": "AMAZON",
            "merchantCity": "Seattle",
            "merchantCountry": "US",
            "merchantCategory": "Online Shopping",
            "merchantCategoryCode": "5411",
            "cardId": "card_123",
            "cardType": "virtual",
            "companyId": "company_456",
            "userId": "user_789",
            "userFirstName": "John",
            "userLastName": "Doe",
            "userEmail": "john.doe@example.com",
            "status": "pending",
            "authorizedAt": "2026-01-27T15:30:00.000Z",
            "exchangeRate": 1.11,
            "threeDSecure": true
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `spend` for this webhook
`spend.amount`	`number`	Transaction amount in USD cents
`spend.currency`	`string`	Currency code (for example, `usd`)
`spend.localAmount`	`number` (optional)	Transaction amount in local currency
`spend.localCurrency`	`string` (optional)	Local currency code
`spend.authorizedAmount`	`number` (optional)	The authorized amount
`spend.authorizationMethod`	`string` (optional)	Method of authorization
`spend.merchantName`	`string`	Merchant name
`spend.merchantCity`	`string`	Merchant city
`spend.merchantCountry`	`string`	Merchant country
`spend.merchantCategory`	`string`	Merchant category description
`spend.merchantCategoryCode`	`string`	Merchant category code (MCC)
`spend.merchantId`	`string` (optional)	Merchant ID
`spend.cardId`	`string`	The card ID used for the transaction
`spend.cardType`	`string`	The card type (`virtual` or `physical`)
`spend.companyId`	`string` (optional)	Company ID (for corporate cards)
`spend.userId`	`string`	The user ID
`spend.userFirstName`	`string`	User’s first name
`spend.userLastName`	`string` (optional)	User’s last name
`spend.userEmail`	`string`	User’s email
`spend.status`	`string`	Transaction status (`pending` or `declined`)
`spend.declinedReason`	`string` (optional)	Reason for decline (only when status is `declined`)
`spend.authorizedAt`	`string`	ISO 8601 timestamp of authorization
`spend.signature`	`string` (optional)	Signature for verification
`spend.timestamp`	`number` (optional)	Unix timestamp
`spend.exchangeRate`	`number` (optional)	The exchange rate used to convert the local transaction amount to the settlement amount (USD). Present for international transactions where currency conversion occurred.
`spend.threeDSecure`	`boolean` (optional)	Indicates whether 3D Secure authentication was used for the transaction
`spend.iso8583.de41`	`string` (optional)	Terminal ID (ISO 8583 Data Element 41)
`spend.tokenizedSource`	`string` (optional)	Source of tokenization (for example, `apple_pay`, `google_pay`)
`spend.fundMovements`	`array` (optional)	On-chain fund movements backing the transaction, ordered oldest first. Requires `transaction.created` version `1.3.0` or later. See Fund movements.

`payment`

Rain sends the payment webhook when you initiate a payment on-chain. Rain sends a separate webhook when the payment completes.

Payload

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resource": "transaction",
    "action": "created",
    "version": "1.0.0",
    "body": {
        "id": "txn_abc123",
        "type": "payment",
        "payment": {
            "amount": 50000,
            "currency": "usd",
            "chainId": 1,
            "walletAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
            "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
            "companyId": "company_456",
            "status": "pending"
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `payment` for this webhook
`payment.amount`	`number`	Payment amount
`payment.currency`	`string`	Currency code (for example, `usd`)
`payment.chainId`	`number`	Blockchain chain ID (for example, `1` for Ethereum mainnet)
`payment.walletAddress`	`string`	Wallet address the payment was sent from (EIP-55 checksummed format)
`payment.transactionHash`	`string`	On-chain transaction hash
`payment.companyId`	`string` (optional)	Company ID (for corporate accounts)
`payment.userId`	`string` (optional)	User ID (for consumer accounts)
`payment.status`	`string`	Always `pending` for this webhook

`transaction.updated`

Rain sends this webhook whenever it updates a transaction. The transaction may not exist yet when this update arrives.

`spend`

Rain triggers this webhook for events such as incremental authorizations or refunds.

Payload

{
    "resource": "transaction",
    "action": "updated",
    "version": "1.1.0",
    "body": {
        "id": "txn_abc123",
        "type": "spend",
        "spend": {
            "amount": 5000,
            "currency": "usd",
            "merchantName": "SUSPICIOUS MERCHANT",
            "merchantCity": "Unknown",
            "merchantCountry": "XX",
            "merchantCategory": "Miscellaneous",
            "merchantCategoryCode": "9999",
            "cardId": "card_123",
            "cardType": "virtual",
            "userId": "user_789",
            "userFirstName": "John",
            "userLastName": "Doe",
            "userEmail": "john.doe@example.com",
            "status": "declined",
            "declinedReason": "suspected fraud",
            "authorizedAt": "2026-01-27T15:30:00.000Z"
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `spend` for this webhook
`spend.amount`	`number`	Transaction amount in USD cents
`spend.currency`	`string`	Currency code (for example, `usd`)
`spend.localAmount`	`number` (optional)	Transaction amount in local currency
`spend.localCurrency`	`string` (optional)	Local currency code
`spend.authorizedAmount`	`number` (optional)	The authorized amount
`spend.authorizationUpdateAmount`	`number` (optional)	The amount by which the authorization changed
`spend.authorizationMethod`	`string` (optional)	Method of authorization
`spend.merchantName`	`string`	Merchant name
`spend.merchantCity`	`string`	Merchant city
`spend.merchantCountry`	`string`	Merchant country
`spend.merchantCategory`	`string`	Merchant category description
`spend.merchantCategoryCode`	`string`	Merchant category code (MCC)
`spend.merchantId`	`string` (optional)	Merchant ID
`spend.cardId`	`string`	The card ID used for the transaction
`spend.cardType`	`string`	The card type (`virtual` or `physical`)
`spend.companyId`	`string` (optional)	Company ID (for corporate cards)
`spend.userId`	`string`	The user ID
`spend.userFirstName`	`string`	User’s first name
`spend.userLastName`	`string` (optional)	User’s last name
`spend.userEmail`	`string`	User’s email
`spend.status`	`string`	Transaction status (`pending`, `reversed`, or `declined`)
`spend.declinedReason`	`string` (optional)	Reason for decline (only when status is `declined`)
`spend.authorizedAt`	`string`	ISO 8601 timestamp of authorization
`spend.signature`	`string` (optional)	Signature for verification
`spend.timestamp`	`number` (optional)	Unix timestamp
`spend.enrichedMerchantName`	`string` (optional)	The enriched (cleaned-up) name of the merchant
`spend.enrichedMerchantCategory`	`string` (optional)	The enriched (cleaned-up) category of the merchant
`spend.enrichedMerchantIcon`	`string` (optional)	URL of the enriched merchant’s icon
`spend.iso8583.de41`	`string` (optional)	Terminal ID (ISO 8583 Data Element 41)
`spend.exchangeRate`	`number` (optional)	The exchange rate used to convert the local transaction amount to the settlement amount (USD). Present for international transactions where currency conversion occurred.
`spend.fundMovements`	`array` (optional)	On-chain fund movements backing the transaction, ordered oldest first. Requires `transaction.updated` version `1.2.0` or later. See Fund movements.

The status field can take these values:

Status	Description
`pending`	Transaction is still pending settlement
`reversed`	Authorization was reversed (for example, voided by merchant)
`declined`	Transaction was declined after initial authorization

`transaction.completed`

Rain sends this webhook once, when a transaction first closes. If further network messages arrive for a transaction that has already closed, Rain does not send a second transaction.completed, so you can reconcile on this event as the single settlement signal. The transaction may not exist yet when this update arrives.

`spend`

Rain sends the spend webhook when a transaction settles. No response is required.

Payload

{
    "resource": "transaction",
    "action": "completed",
    "version": "1.3.0",
    "body": {
        "id": "txn_abc123",
        "type": "spend",
        "spend": {
            "amount": 5500,
            "currency": "usd",
            "localAmount": 4950,
            "localCurrency": "EUR",
            "authorizedAmount": 5000,
            "merchantName": "RESTAURANT XYZ",
            "merchantCity": "Miami",
            "merchantCountry": "US",
            "merchantCategory": "Restaurants",
            "merchantCategoryCode": "5812",
            "cardId": "card_123",
            "cardType": "physical",
            "companyId": "company_456",
            "userId": "user_789",
            "userFirstName": "John",
            "userLastName": "Doe",
            "userEmail": "john.doe@example.com",
            "status": "completed",
            "authorizedAt": "2026-01-27T19:30:00.000Z",
            "postedAt": "2026-01-29T08:15:00.000Z",
            "exchangeRate": 1.11,
            "completionReason": "settlement",
            "isForcePosted": true,
            "closedAuthorizationTransactionId": "txn_auth456",
            "threeDSecure": true
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `spend` for this webhook
`spend.amount`	`number`	Final settled transaction amount in USD cents
`spend.currency`	`string`	Currency code (for example, `usd`)
`spend.localAmount`	`number` (optional)	Transaction amount in local currency
`spend.localCurrency`	`string` (optional)	Local currency code
`spend.authorizedAmount`	`number` (optional)	The original authorized amount
`spend.authorizationMethod`	`string` (optional)	Method of authorization
`spend.merchantName`	`string`	Merchant name
`spend.merchantCity`	`string`	Merchant city
`spend.merchantCountry`	`string`	Merchant country
`spend.merchantCategory`	`string`	Merchant category description
`spend.merchantCategoryCode`	`string`	Merchant category code (MCC)
`spend.merchantId`	`string` (optional)	Merchant ID
`spend.cardId`	`string`	The card ID used for the transaction
`spend.cardType`	`string`	The card type (`virtual` or `physical`)
`spend.companyId`	`string` (optional)	Company ID (for corporate cards)
`spend.userId`	`string`	The user ID
`spend.userFirstName`	`string`	User’s first name
`spend.userLastName`	`string` (optional)	User’s last name
`spend.userEmail`	`string`	User’s email
`spend.status`	`string`	Always `completed` for this webhook
`spend.authorizedAt`	`string`	ISO 8601 timestamp of original authorization
`spend.postedAt`	`string`	ISO 8601 timestamp when the transaction was posted or settled
`spend.signature`	`string` (optional)	Signature for verification
`spend.timestamp`	`number` (optional)	Unix timestamp
`spend.exchangeRate`	`number` (optional)	The exchange rate used to convert the local transaction amount to the settlement amount (USD). Present for international transactions where currency conversion occurred.
`spend.completionReason`	`string` (optional)	The reason the transaction was completed
`spend.isForcePosted`	`boolean` (optional)	Indicates whether this transaction was force posted. Present when the value is explicitly `true` or `false`.
`spend.closedAuthorizationTransactionId`	`string` (optional)	The ID of the authorization transaction that was closed when this force-posted settlement arrived. Present only when the force post closed an existing authorization.
`spend.enrichedMerchantName`	`string` (optional)	The enriched (cleaned-up) name of the merchant
`spend.enrichedMerchantCategory`	`string` (optional)	The enriched (cleaned-up) category of the merchant
`spend.enrichedMerchantIcon`	`string` (optional)	URL of the enriched merchant’s icon
`spend.threeDSecure`	`boolean` (optional)	Indicates whether 3D Secure authentication was used for the transaction
`spend.fundMovements`	`array` (optional)	On-chain fund movements backing the transaction, ordered oldest first. Requires `transaction.completed` version `1.4.0` or later. See Fund movements.

The completionReason field can take these values:

Value	Description
`settlement`	Normal settlement from the payment network
`stale_authorization_closure`	Authorization expired due to age without settlement
`authorization_reversal`	Merchant fully reversed the authorization amount to zero
`refund`	Transaction was refunded
`chargeback`	Transaction was charged back
`manual_closure`	Manually closed by an administrator
`reprocessed_settlement`	Replayed force-posted settlement

The localAmount and localCurrency fields are populated when the transaction involves a foreign currency or when it is a standard settlement where the authorized amount equals the final settled amount. These fields may be undefined in certain scenarios, such as partial captures where the authorized and settled amounts differ.

`payment`

Rain sends the payment webhook when an initiated on-chain payment completes.

Payload

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resource": "transaction",
    "action": "completed",
    "version": "1.0.0",
    "body": {
        "id": "txn_abc123",
        "type": "payment",
        "payment": {
            "amount": 50000,
            "currency": "usd",
            "chainId": 1,
            "walletAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
            "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
            "companyId": "company_456",
            "status": "completed",
            "postedAt": "2026-01-27T16:45:00.000Z"
        }
    }
}

Field	Type	Description
`id`	`string`	The transaction ID
`type`	`string`	Always `payment` for this webhook
`payment.amount`	`number`	Payment amount
`payment.currency`	`string`	Currency code (for example, `usd`)
`payment.chainId`	`number`	Blockchain chain ID (for example, `1` for Ethereum mainnet)
`payment.walletAddress`	`string`	Wallet address the payment was sent from (EIP-55 checksummed format)
`payment.transactionHash`	`string`	On-chain transaction hash
`payment.companyId`	`string` (optional)	Company ID (for corporate accounts)
`payment.userId`	`string` (optional)	User ID (for consumer accounts)
`payment.status`	`string`	Always `completed` for this webhook
`payment.postedAt`	`string`	ISO 8601 timestamp when the payment was posted or settled

`transactionTransfer.created`

Rain sends this webhook whenever it creates a transfer transaction.

`transfer`

Rain sends the transfer webhook when you initiate a new transfer. Rain sends a separate webhook when the transfer completes.

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

All three transactionTransfer events carry the same transfer object. The status and which optional fields are present vary by lifecycle stage.

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 (for example, `"100.00"`)
`transfer.source.currency`	`string`	Source currency code
`transfer.source.rail`	`string`	Source rail (for example, `onchain`, `wire`)
`transfer.source.referenceId`	`string` (optional)	Source reference ID
`transfer.source.address`	`object` (optional)	Source address (see address types)
`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)
`transfer.depositAddress`	`object` (optional)	Deposit address for the transfer (see deposit address types)
`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.sender`	`object` (optional)	Sender fee you configured, with the same `currency`, `amount`, and `amountUSD` shape. Present on transfers with a sender fee.
`transfer.fees.developer`	`object` (optional)	Deprecated alias of `fees.sender`; read `sender` instead. Same `currency`, `amount`, and `amountUSD` shape.
`transfer.exchangeRate`	`number` (optional)	Exchange rate applied
`transfer.status`	`string`	Transfer status at creation. Always `pending` or `awaiting_transfer`, the values that describe a transfer that hasn’t started processing yet.
`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
`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. Requires version `1.1.0` or later.

`transactionTransfer.updated`

Rain sends this webhook whenever a transfer’s status changes after creation, except when it reaches settled.

`transfer`

Rain sends the transfer webhook when a transfer’s status changes after creation, including non-success terminal states (failed, cancelled, expired, refunded).

Payload

{
    "resource": "transactionTransfer",
    "action": "updated",
    "version": "1.0.0",
    "body": {
        "id": "txn_abc123",
        "type": "transfer",
        "transfer": {
            "source": {
                "amount": "1000.00",
                "currency": "usdc",
                "rail": "onchain",
                "referenceId": "ref_123",
                "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": "processing",
            "createdAt": "2026-01-27T15:30:00.000Z",
            "updatedAt": "2026-01-27T16:00:00.000Z",
            "quoteId": "355e0a5c-76a5-4d13-bcee-f2ad39abe710",
            "expiresAt": "2026-01-28T15:30:00.000Z"
        }
    }
}

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 (for example, `"100.00"`)
`transfer.source.currency`	`string`	Source currency code
`transfer.source.rail`	`string`	Source rail (for example, `onchain`, `wire`)
`transfer.source.referenceId`	`string` (optional)	Source reference ID
`transfer.source.address`	`object` (optional)	Source address (see address types)
`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)
`transfer.depositAddress`	`object` (optional)	Deposit address for the transfer (see deposit address types)
`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.sender`	`object` (optional)	Sender fee you configured, with the same `currency`, `amount`, and `amountUSD` shape. Present on transfers with a sender fee.
`transfer.fees.developer`	`object` (optional)	Deprecated alias of `fees.sender`; read `sender` instead. Same `currency`, `amount`, and `amountUSD` shape.
`transfer.exchangeRate`	`number` (optional)	Exchange rate applied
`transfer.status`	`string`	Transfer status. Never `settled`: a separate `transactionTransfer.completed` webhook covers that outcome. One of `pending`, `awaiting_transfer`, `processing`, `pending_review`, `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
`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. Requires version `1.1.0` or later.

The updated webhook fires for in-flight progress (processing) and non-success terminals (failed, cancelled, expired, refunded).

`transactionTransfer.completed`

Rain sends this webhook when a transfer settles successfully at its destination.

`transfer`

Rain sends the transfer webhook when a transfer settles at the destination.

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

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 (for example, `"100.00"`)
`transfer.source.currency`	`string`	Source currency code
`transfer.source.rail`	`string`	Source rail (for example, `onchain`, `wire`)
`transfer.source.referenceId`	`string` (optional)	Source reference ID
`transfer.source.address`	`object` (optional)	Source address (see address types)
`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)
`transfer.depositAddress`	`object` (optional)	Deposit address for the transfer (see deposit address types)
`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.sender`	`object` (optional)	Sender fee you configured, with the same `currency`, `amount`, and `amountUSD` shape. Present on transfers with a sender fee.
`transfer.fees.developer`	`object` (optional)	Deprecated alias of `fees.sender`; read `sender` instead. Same `currency`, `amount`, and `amountUSD` shape.
`transfer.exchangeRate`	`number` (optional)	Exchange rate applied
`transfer.status`	`string`	Transfer status. Always `settled` for this webhook.
`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
`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. Requires version `1.1.0` or later.

Transfer object reference

The nested address fields and the status values used in the transfer object are detailed below.

Address types

The source.address and destination.address fields can each take one of the following shapes. An onchain address contains these fields:

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

A payment account address contains these fields:

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

Deposit address types

The depositAddress field can take one of the following shapes. A fiat deposit address contains these fields:

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 or memo

An onchain deposit address contains these fields:

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

Transfer status values

The status field reflects where the transfer is in its lifecycle:

Status	Description
`pending`	Transfer has been initiated
`awaiting_transfer`	Waiting for the incoming funds for the transfer
`processing`	Transfer is being processed
`pending_review`	Transfer is held for review before it continues processing
`settled`	Transfer has been completed successfully
`failed`	Transfer has failed
`cancelled`	Transfer was cancelled
`expired`	Transfer expired before completion
`refunded`	Transfer was refunded

Fund movements

The spend transaction.created, transaction.updated, and transaction.completed webhooks can include a fundMovements array that describes the on-chain movements backing the card transaction, such as the authorization pull that reserved funds on-chain, ordered oldest first. You receive this field only if your tenant is opted in to the webhook version that added it (transaction.created 1.3.0, transaction.updated 1.2.0, transaction.completed 1.4.0). Earlier versions never include it, and the array is empty when no on-chain movements back the transaction. Each entry in fundMovements has the following shape:

Field	Type	Description
`hash`	`string`	The on-chain transaction hash for this movement.
`chainId`	`string`	The chain identifier where the movement settled, as a hex string (for example, `0x2105` for Base). `collateral.chainId` and `payment.chainId` elsewhere on this page are decimal numbers instead.
`kind`	`string`	The type of fund movement. See the values below.
`direction`	`string`	The direction of the movement: `debit` (funds pulled) or `credit` (funds returned, as on a `reversal`).
`amountCents`	`number`	The amount moved, in cents.
`occurredAt`	`string`	ISO 8601 timestamp of when the movement occurred on-chain.
`currency`	`string`	The currency of the movement. Requires `transaction.created` version `1.4.0` or `transaction.completed` version `1.5.0`; `transaction.updated` entries don’t carry it.

The kind field can take these values:

Value	Description
`auth`	Initial authorization pull.
`incremental_auth`	Additional pull for an incremental authorization.
`force_post`	Pull backing a force-posted settlement.
`over_capture`	Pull covering a settlement that exceeded the authorized amount.
`sweep`	Pull that sweeps remaining funds for the transaction.
`reversal`	Funds returned on-chain when an authorization is reversed.

What’s next

Sample webhooks

See worked examples of a spend moving through these events end to end.

Decline reasons

Look up what a declinedReason value means and what to do about it.

Overview

Compliance

Cards

Payments

Webhooks

Webhook Events

Transaction Events

`transaction.requested`

`spend`

Response

`transaction.created`

`collateral`

`spend`

`payment`

`transaction.updated`

`spend`

`transaction.completed`

`spend`

`payment`

`transactionTransfer.created`

`transfer`

`transactionTransfer.updated`

`transfer`

`transactionTransfer.completed`

`transfer`

Transfer object reference

Address types

Deposit address types

Transfer status values

Fund movements

What’s next

Sample webhooks

Decline reasons

​transaction.requested

​spend

​Response

​transaction.created

​collateral

​spend

​payment

​transaction.updated

​spend

​transaction.completed

​spend

​payment

​transactionTransfer.created

​transfer

​transactionTransfer.updated

​transfer

​transactionTransfer.completed

​transfer

​Transfer object reference

​Address types

​Deposit address types

​Transfer status values

​Fund movements

​What’s next

Sample webhooks

Decline reasons

`transaction.requested`

`spend`

Response

`transaction.created`

`collateral`

`spend`

`payment`

`transaction.updated`

`spend`

`transaction.completed`

`spend`

`payment`

`transactionTransfer.created`

`transfer`

`transactionTransfer.updated`

`transfer`

`transactionTransfer.completed`

`transfer`

Transfer object reference

Address types

Deposit address types

Transfer status values

Fund movements

What’s next