Sender Fees

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

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

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.

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.

Quote Request with Sender Fee

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:

{
  "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:

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

{
  "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.

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.

Payment Route Request with Sender Fees

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

{
  "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:

{
  "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 for the full transfer flow
Learn about Offramps for USD payment route-based withdrawals
Learn about Onramps for fiat deposits

Introduction

Set Up Money Movement

Money Movement

Subtenants

Reconciliation

Sender Fees

Overview

How Fees Work

Fee Types

Fee Economics

Transfers

Quote Request with Sender Fee

Quote Response

Transfer Request

Transfer Response

Payment Routes

Payment Route Request with Sender Fees

Payment Route Response

Example Transfer Through a Payment Route

Summary

Next Steps

​Overview

​How Fees Work

​Fee Types

​Fee Economics

​Transfers

​Quote Request with Sender Fee

​Quote Response

​Transfer Request

​Transfer Response

​Payment Routes

​Payment Route Request with Sender Fees

​Payment Route Response

​Example Transfer Through a Payment Route

​Summary

​Next Steps

Overview

How Fees Work

Fee Types

Fee Economics

Transfers

Quote Request with Sender Fee

Quote Response

Transfer Request

Transfer Response

Payment Routes

Payment Route Request with Sender Fees

Payment Route Response

Example Transfer Through a Payment Route

Summary

Next Steps