> ## 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.

# Sender Fees

> Configure custom fees on transfers and payment routes to manage your revenue and subsidize user costs.

## Overview

Sender fees allow you to set a custom fee on transfers and payment routes that is charged to the end user. The sender fee is the **total** fee deducted from the source amount — it is not added on top of the Rain fee. This gives you control over your pricing and revenue model.

When not set, the sender fee automatically defaults to be equal to the Rain fee — meaning the end user is charged the Rain fee and no additional margin is applied.

## How Fees Work

### Fee Types

| Type       | Description                                           |
| ---------- | ----------------------------------------------------- |
| `flat`     | A fixed fee amount denominated in the source currency |
| `variable` | A percentage-based fee applied to the source amount   |

### Fee Economics

The sender fee is the **only** fee deducted from the source amount. The destination amount is calculated as:

> **(source amount - sender fee) × exchange rate = destination amount**

The `rain` returned in the response is informational — it represents Rain's cost for the transaction. The net between the sender fee and the Rain fee determines your economics:

* **Sender fee > Rain fee**: You receive the difference as a payout (your margin)
* **Sender fee = Rain fee**: No margin — the user pays exactly the Rain fee (this is the default)
* **Sender fee \< Rain fee**: You are subsidising the transaction — you will be invoiced for the difference

<Info>
  Sender fees must be enabled for your account. Contact your Rain representative for details and to configure fee limits.
</Info>

## Transfers

For transfers, you set a single `senderFee` on the quote request. Quote requests accept `flat` fees only — since you know the source amount at quote time, you can calculate a percentage-based fee on your end and pass it as a flat amount.

<Info>
  `senderFee` was previously named `developerFee`. You can still pass `developerFee` for backward compatibility, but it is deprecated, so use `senderFee` instead. If you provide both, `senderFee` takes precedence. In responses, the fee appears under `fees.sender`.
</Info>

### Quote Request with Sender Fee

```bash theme={null}
curl -X POST https://api.rain.com/v1/quotes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "amount": 100,
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "senderFee": {
      "type": "flat",
      "amount": "2.00"
    }
  }'
```

### Quote Response

The response reflects the sender fee as set in the request:

```json theme={null}
{
  "id": "q-8a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "teamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "source": {
    "amount": 100,
    "currency": "usdc",
    "rail": "base"
  },
  "destination": {
    "amount": 411600,
    "currency": "cop",
    "rail": "co_ach",
    "address": {
      "type": "paymentAccount",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "exchangeRate": 4200,
  "fees": {
    "rain": {
      "currency": "usdc",
      "amount": 1,
      "amountUSD": 1
    },
    "sender": {
      "currency": "usdc",
      "amount": 2,
      "amountUSD": 2
    }
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:45:00Z"
}
```

In this example, the source amount is 100 USDC. The sender fee of 2 USDC is deducted, so 98 USDC is converted at 4200 COP/USDC, resulting in a destination amount of 411,600 COP. The `rain` of 1 USDC is informational — it represents Rain's cost. Since the sender fee (2 USDC) exceeds the Rain fee (1 USDC), you receive 1 USDC as a payout.

### Transfer Request

The transfer is created using the quote as usual — no additional fee configuration is needed:

```bash theme={null}
curl -X POST https://api.rain.com/v1/transfers \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "q-8a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "transferMessage": "Payment for services"
  }'
```

### Transfer Response

```json theme={null}
{
  "id": "t-1234abcd-5678-90ef-ghij-klmnopqrstuv",
  "type": "transfer",
  "transfer": {
    "source": {
      "amount": 100,
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "amount": 411600,
      "currency": "cop",
      "rail": "co_ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "exchangeRate": 4200,
    "fees": {
      "rain": {
        "currency": "usdc",
        "amount": 1,
        "amountUSD": 1
      },
      "sender": {
        "currency": "usdc",
        "amount": 2,
        "amountUSD": 2
      }
    },
    "teamId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "quoteId": "q-8a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "status": "created",
    "createdAt": "2025-01-15T10:40:00Z",
    "updatedAt": "2025-01-15T10:40:00Z",
    "expiresAt": "2025-01-15T11:40:00Z",
    "depositAddress": {
      "type": "onchain",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    }
  }
}
```

## Payment Routes

For payment routes, the source amount is not known in advance — users can send any amount at any time. To support granular fee configuration, payment routes use a `senderFees` field which accepts an array of fee definitions. This allows you to configure both a flat and a variable fee component together.

<Info>
  `senderFees` was previously named `developerFees`. You can still pass `developerFees` for backward compatibility, but it is deprecated, so use `senderFees` instead. If you provide both, `senderFees` takes precedence.
</Info>

### Payment Route Request with Sender Fees

```bash theme={null}
curl -X POST https://api.rain.com/v1/payment-routes \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "11111111-1111-1111-1111-111111111111",
    "source": {
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "currency": "usd",
      "rail": "ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "senderFees": [
      {
        "type": "flat",
        "amount": "1.00"
      },
      {
        "type": "variable",
        "amount": "0.5"
      }
    ]
  }'
```

In this example, the payment route is configured with two sender fee components:

* A **flat fee** of 1.00 USDC per transfer
* A **variable fee** of 0.5% of the source amount

### Payment Route Response

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "11111111-1111-1111-1111-111111111111",
  "status": "active",
  "source": {
    "currency": "usdc",
    "rail": "base"
  },
  "destination": {
    "currency": "usd",
    "rail": "ach",
    "address": {
      "type": "paymentAccount",
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    }
  },
  "refundAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "senderFees": [
    {
      "type": "flat",
      "amount": "1.00"
    },
    {
      "type": "variable",
      "amount": "0.5"
    }
  ],
  "developerFees": [
    {
      "type": "flat",
      "amount": "1.00"
    },
    {
      "type": "variable",
      "amount": "0.5"
    }
  ],
  "depositAddress": {
    "type": "onchain",
    "address": "0xabcdef1234567890abcdef1234567890abcdef12"
  },
  "createdAt": "2025-01-15T10:35:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}
```

### Example Transfer Through a Payment Route

When a user sends 200 USDC to the payment route's deposit address, both sender fee components are applied:

| Component                | Calculation | Amount          |
| ------------------------ | ----------- | --------------- |
| Source amount            |             | 200.00 USDC     |
| Sender fee (flat)        | Fixed       | 1.00 USDC       |
| Sender fee (variable)    | 200 × 0.5%  | 1.00 USDC       |
| **Total sender fee**     |             | **2.00 USDC**   |
| **Amount converted**     | 200 - 2.00  | **198.00 USDC** |
| Rain fee (informational) |             | 1.00 USDC       |

The resulting transfer transaction reflects both fee components combined:

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "transfer",
  "transfer": {
    "source": {
      "amount": "200.00",
      "currency": "usdc",
      "rail": "base"
    },
    "destination": {
      "amount": "198.00",
      "currency": "usd",
      "rail": "ach",
      "address": {
        "type": "paymentAccount",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    },
    "depositAddress": {
      "type": "onchain",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    },
    "exchangeRate": 1.0,
    "fees": {
      "rain": {
        "currency": "usdc",
        "amount": 1,
        "amountUSD": 1
      },
      "sender": {
        "currency": "usdc",
        "amount": 2,
        "amountUSD": 2
      }
    },
    "status": "settled",
    "createdAt": "2025-01-15T10:35:00Z",
    "updatedAt": "2025-01-15T10:40:00Z"
  }
}
```

Since the total sender fee (2.00 USDC) exceeds the Rain fee (1.00 USDC), you receive 1.00 USDC as a payout.

## Summary

|                | Transfers                                               | Payment Routes                                                                                   |
| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Field name** | `senderFee` (formerly `developerFee`)                   | `senderFees` (formerly `developerFees`)                                                          |
| **Structure**  | Single fee object                                       | Array of fee objects                                                                             |
| **Fee types**  | `flat` only                                             | `flat` and/or `variable`                                                                         |
| **Why**        | Source amount is known — calculate your fee on your end | Source amount is unknown — configure both flat and variable components for automatic calculation |

## Next Steps

* Learn about [Transfers](/docs/transfers) for the full transfer flow
* Learn about [Offramps](/docs/offramps) for USD payment route-based withdrawals
* Learn about [Onramps](/docs/onramps) for fiat deposits