Payment Routes

These webhooks tell you, without polling the API, when a payment route becomes active and ready to receive deposits, and when a deposit too small to on-ramp arrives on one of your routes. Route activation behaves differently for Partner-Managed and Rain-Managed customers, described below. The following events are available:

Event	Description
`paymentRoute.created`	A payment route becomes active and is ready to receive deposits.
`microDeposit.received`	A deposit below the minimum on-ramp amount arrives on a payment route.

`paymentRoute.created`

This webhook is sent when a payment route becomes active, meaning its virtual account is provisioned and ready to receive deposits. The body is the full payment route, matching the shape returned by GET /v1/payment-routes.

Rain-Managed customers

For customers who are already KYC-approved, Rain provisions the payment route synchronously and returns it directly in the create response, so you do not need to wait for this webhook.

Partner-Managed customers

When you create a payment route for a Partner-Managed customer who has not yet completed KYC, Rain creates the route in a pending state and starts the customer’s KYC. A pending route has no deposit address yet. Once the customer’s KYC is approved, Rain provisions the virtual account, transitions the route to active, and sends the paymentRoute.created webhook with the route’s full details, including the deposit address you use to fund it.

A pending route is returned immediately from the create call so you have its id, but wait for the paymentRoute.created webhook before you share deposit details with the customer.

Payload

{
    "id": "e7c1f0a2-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
    "resource": "paymentRoute",
    "action": "created",
    "version": "1.0.0",
    "body": {
        "id": "a1b2c3d4-5e6f-7081-9234-56789abcdef0",
        "userId": "11111111-1111-1111-1111-111111111111",
        "status": "active",
        "source": {
            "currency": "usd",
            "rail": "ach"
        },
        "destination": {
            "currency": "usdc",
            "rail": "base",
            "address": {
                "type": "onchain",
                "address": "0x1234567890abcdef1234567890abcdef12345678"
            }
        },
        "depositAddress": {
            "type": "fiat",
            "beneficiaryBankName": "SSB BANK",
            "accountNumber": "1234567890",
            "routingNumber": "043087080"
        },
        "createdAt": "2026-06-11T15:30:00.000Z",
        "updatedAt": "2026-06-11T15:30:00.000Z"
    }
}

Field	Type	Description
`id`	`string`	The payment route ID
`userId`	`string` (optional)	The user ID for consumer accounts
`companyId`	`string` (optional)	The company ID for corporate accounts
`status`	`string`	Route status (`active`, `pending`, `frozen`, or `deleted`). This webhook fires when the route reaches `active`
`source.currency`	`string`	Source currency code (for example, `usd`, `usdc`, `mxn`)
`source.rail`	`string`	Source rail (for example, `ach`, `wire`, `base`, `mx_spei`)
`destination.currency`	`string`	Destination currency code
`destination.rail`	`string`	Destination rail
`destination.address`	`object`	Destination address (see Address types)
`destination.referenceId`	`string` (optional)	Destination reference or memo. Only relevant for fiat destinations
`depositAddress`	`object` (optional)	Where the customer funds the route (see Deposit address types). Omitted while a route is `pending`
`refundAddress`	`string` (optional)	Refund wallet address, for onchain-source (off-ramp) routes
`transferMessage`	`string` (optional)	Message attached to transfers from this route
`senderFees`	`array` (optional)	Sender fees applied to the route
`developerFees`	`array` (optional)	Deprecated: use `senderFees` instead. Returns the same values for backward compatibility
`createdAt`	`string`	ISO 8601 timestamp of creation
`updatedAt`	`string`	ISO 8601 timestamp of last update

Address types

The destination address can be one of two shapes. 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 two shapes. Fiat deposit address:

Field	Type	Description
`type`	`string`	Always `fiat`
`beneficiaryName`	`string` (optional)	Beneficiary name
`beneficiaryAddress`	`string` (optional)	Beneficiary address
`beneficiaryBankName`	`string` (optional)	Bank name
`beneficiaryBankAddress`	`string` (optional)	Bank address
`accountNumber`	`string` (optional)	Account number (US bank deposits)
`routingNumber`	`string` (optional)	Routing number (US bank deposits)
`clabeNumber`	`string` (optional)	CLABE (Clave Bancaria Estandarizada) for MXN SPEI deposits
`transferMessage`	`string` (optional)	Transfer message or memo to include with the deposit

Onchain deposit address:

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

`microDeposit.received`

Rain sends this webhook when a deposit smaller than Rain’s $2.00 minimum arrives on one of your payment routes. Rain records the deposit and tells you about it, but never processes it as a transfer, so no transaction is created and no funds are converted. Most of these deposits exist to verify account ownership. When your customer gives their Rain account details to an external service, such as a bank, a payment app, or a payroll provider, that service sends one or more credits under $1.00 and asks the customer to confirm the amounts. Confirming them proves the account is real and belongs to your customer. Use this webhook to show the amounts to your customer so they can finish verifying. Only routes with a fiat deposit address receive these events, because the deposit lands in the route’s bank account.

Do not treat a micro deposit as a balance change. A service that sends a verification deposit usually withdraws it again. Any other deposit under $2.00 stays in the account but Rain still never processes it, so neither kind affects a balance you can spend.

Payload

{
    "id": "f1e2d3c4-b5a6-4789-9012-3456789abcde",
    "resource": "microDeposit",
    "action": "received",
    "version": "1.0.0",
    "body": {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "paymentRouteId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "companyId": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
        "amount": "0.23",
        "currency": "usd",
        "rail": "ach",
        "description": "ACH Credit 999999990000001 EXAMPLE BANK NA ACCTVERIFY",
        "originatorName": "EXAMPLE BANK NA",
        "referenceId": "999999990000001",
        "receivedAt": "2026-06-11T15:30:00Z"
    }
}

Field	Type	Description
`id`	`string`	The micro deposit ID
`paymentRouteId`	`string`	The payment route the deposit arrived on
`userId`	`string` (optional)	The user ID for consumer accounts
`companyId`	`string` (optional)	The company ID for corporate accounts
`amount`	`string`	Deposit amount as a decimal string, for example `"0.23"`
`currency`	`string`	Currency code, always `usd`
`rail`	`string`	Rail the deposit arrived on, either `ach` or `wire`
`description`	`string` (optional)	Bank memo. Trial deposits carry `ACCTVERIFY`
`originatorName`	`string` (optional)	Name of the party that sent the deposit
`referenceId`	`string` (optional)	ACH trace number, or IMAD for a wire
`receivedAt`	`string`	ISO 8601 timestamp of when the deposit arrived

amount is a decimal string, not minor units. A "0.23" value means 23 cents.

Overview

Compliance

Cards

Payments

Webhooks

Webhook Events

Payment Routes

`paymentRoute.created`

Rain-Managed customers

Partner-Managed customers

Address types

Deposit address types

`microDeposit.received`

​paymentRoute.created

​Rain-Managed customers

​Partner-Managed customers

​Address types

​Deposit address types

​microDeposit.received

`paymentRoute.created`

Rain-Managed customers

Partner-Managed customers

Address types

Deposit address types

`microDeposit.received`