> ## 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.
# Payment Routes
> React to payment route activation and incoming micro deposits in real time instead of polling, so you can share deposit details the moment a route is ready and confirm account verification deposits as they arrive.
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`](#paymentroute-created) | A payment route becomes active and is ready to receive deposits. |
| [`microDeposit.received`](#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.
```json Payload theme={null}
{
"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](#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](#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.
```json Payload theme={null}
{
"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.