Rewards Overview

Learn how Raindrops works and what you need to configure, display, or integrate.

Rewards is infrastructure that lets partners add a points program to their card product. Cardholders earn points on posted card transactions, and can access multiple redemption options, including statement credits (functionally similar to cashback) and travel rewards.

Rain supports three points modes: Rain-Managed (default), where Rain handles the full lifecycle onchain, and two Partner-Managed modes for partners that own part or all of the rewards orchestration.

Points Modes

Mode	Description
Rain-Managed	Rain calculates points, mints them onchain as tokens (ERC-20 on EVM chains, SPL on Solana), and handles redemptions. Points live in the cardholder’s Rain collateral contract.
Partner-Managed (Onchain)	You hold the minter key and control per-user wallets. You mint tokens, process burns, and update your own ledger when necessary. Rain orchestrates travel redemptions and queries your server for end user balances via synchronous webhook.
Partner-Managed (Offchain)	No onchain rewards activity. Rain keeps the canonical per-user points ledger in its database, supports adjustment APIs, and handles travel redemptions against that DB balance. For statement credits, you call Rain’s API to debit the DB points balance, then apply the cardholder credit in your own system.

Partner-managed programs should choose Onchain if your end users are crypto native, hold crypto wallets, and want to self-custody their assets, or if you otherwise want to take advantage of the extensibility/interoperability of public blockchain networks. If you want to optimize for simplicity and ease of integration, choose Offchain.

How It Works (Rain-Managed)

1. Earn: When a transaction settles, points entries are created in a pending state
2. Settle: When the statement closes, points move from pending to ready
3. Mint: At liquidation, ready points are minted onchain to the user’s collateral contract
4. Redeem: Cardholder uses points for statement credits or travel bookings

How It Works (Partner-Managed)

Partner-Managed behavior depends on whether balances live onchain or in Rain’s database:

1. Earn: In onchain mode, calculate points from transaction.spend.completed webhooks. In offchain mode, Rain calculates card-spend points from your configured earn rates and stores them in the DB ledger.
2. Mint: In onchain mode, mint tokens to user wallets you control. In offchain mode, Rain marks points as minted in the DB without submitting an onchain transaction.
3. Redeem: For statement credits, onchain partners handle the redemption in their own system, while offchain partners call Rain to debit the DB points balance and then apply the credit themselves. For travel redemptions, Rain orchestrates the booking and checks balances against your webhook (onchain) or Rain’s database (offchain).

See Earning and Minted for mode-specific details.

What You Configure

During onboarding, you will:

• Choose a points mode: Rain-Managed (default), Partner-Managed (Onchain), or Partner-Managed (Offchain)
• Set earn rates (Rain-Managed and Partner-Managed Offchain): Define how many points cardholders earn per category. See Configuring Rates.
• Choose card types: Consumer cards earn points by default. Corporate cards earn only after you ask Rain to turn them on. See Eligible Programs.

Billing

Rewards allows you to take advantage of the same economics that have made programs like Skymiles the most profitable division of Delta Airlines. When cardholders earn points, there are no cash expenses incurred by you or Rain. Points are created as either tokens or database entries depending on your configuration, and you realize the benefit of rewards-based spend lift immediately. Cash expenses are only incurred later at redemption time, so you can take advantage of the float created by the time value of money and breakage when points go unredeemed.

Rain will include all expenses incurred by rewards redemptions for a given period on that period’s invoice. If a reward is refunded after you have been billed for it, you will see a credit on your next invoice.

For clients with more complex accounting needs, please inquire for alternative reward funding mechanisms.

What Is Automatic

What Rain handles automatically depends on your points mode:

Capability	Rain-Managed	Partner-Managed (Onchain)	Partner-Managed (Offchain)
Point calculation	✓	✓	✓
Onchain minting	✓	You handle	N/A
Statement-credit redemptions	✓	You handle	Both handle
Travel-portal redemptions	Rain orchestrates	Rain orchestrates	✓
Charge reconciliation	✓	✓	✓

Reading Balances

Use these endpoints to display points data in your app:

• GET /issuing/raindrops/balance - Returns the full onchain, withheld, pending, statement-credit, and available breakdown for Rain-Managed tenants. For Partner-Managed Offchain tenants, returns availablePoints and pendingPoints. Partner-Managed Onchain tenants receive 405 because balances are read from your system.
• GET /issuing/raindrops/activity — Returns a paginated list of earn and redeem events

Point amounts in API responses are JSON strings to preserve precision for values beyond 2^53.

For Partner-Managed (Onchain), you maintain balances in your own system. Rain queries your balance via the raindrop_balance.requested webhook when needed for travel redemptions.

External endpoints require the Api-Key header. See Authenticating with the API for details.

Temporary Freezes

Rain can temporarily freeze Raindrops API writes and Raindrops withdrawal signatures for one program or for all programs. While a freeze is active:

• Every POST request under /issuing/raindrops returns 503 Service Unavailable with the message Raindrops are temporarily frozen. Please retry later. This covers travel redemptions and refunds, custom redemptions, statement-credit redemptions, points adjustments, and POST /simulate/raindrops/mint-pending.
• Withdrawal signature requests for Raindrops tokens, including the burn for a travel or custom redemption, return 422 Unprocessable Entity with the same message.
• Read endpoints keep working, including GET /issuing/raindrops/balance, GET /issuing/raindrops/activity, and GET /issuing/raindrops/travel-redemptions/balance.
• Card-spend earning, the scheduled mint, and onchain settlement keep running.
• Rain-Managed statement credits paid from collateral are not frozen, because they use a payment signature rather than a withdrawal signature.

Retry refused requests after the freeze lifts.

Corporate Programs

In a corporate program, each employee earns points on their own card spend, and the points go into one shared balance for the company. Corporate cards earn only after Rain turns them on for your program. See Eligible Programs.

Company Owner and Redemptions

Only the company owner can redeem the shared balance. The company owner is the initialUser you sent when you created the company with POST /issuing/applications/company. It cannot be changed. Company responses do not include the owner’s userId, so to find it, call GET /issuing/users with the company’s companyId and the initialUser email.

POST /issuing/raindrops/custom-redemption, POST /issuing/raindrops/statement-credit, and POST /issuing/raindrops/travel-redemptions return 403 with the message Only the company owner can redeem points for a corporate team when the request is for any other employee. This applies in every points mode. Rain checks ownership first, before it checks whether Raindrops are enabled or whether your points mode supports the endpoint. Another employee gets this 403 even where the owner would get 405. Route redemptions to the company owner, or hide redemption options from other employees.

Rain-Managed statement credits are company collateral payments, not redemption requests, so they have no owner check. Rain records each one under the company owner. See Statement Credit Redemptions.

For Rain-Managed travel and custom redemptions on corporate cards, request the burn signature with the company’s ID instead of the user’s. See Request the burn signature.

Balances and Activity

Rain returns the company’s shared balance for whichever employee you pass as userId:

• Rain-Managed: GET /issuing/raindrops/balance returns the company’s balance for any employee. onChainPoints is the balance held by the company’s contract, and withheldPoints, pendingPoints, and pendingStatementCredits cover every employee. availablePoints is onChainPoints minus withheldPoints. pendingPoints and pendingStatementCredits are separate fields that are not part of availablePoints, and pendingStatementCredits is in cents. GET /issuing/raindrops/travel-redemptions/balance returns the company’s onchain points minus withheld points.
• Partner-Managed (Offchain): GET /issuing/raindrops/balance and GET /issuing/raindrops/travel-redemptions/balance return the company’s minted points, minus redemptions that have not failed, across every employee.
• Partner-Managed (Onchain): You hold balances in your own system, so pool them there. Answer every raindrop_balance.requested webhook for an employee with the company’s shared balance. When the travel portal shows a balance, the webhook carries the ID of the employee who is viewing it. When the owner books travel, it carries the owner’s ID. If you answer the booking request with the owner’s personal balance, the owner cannot spend points that other employees earned.

GET /issuing/raindrops/activity stays per user. An employee sees only their own earnings, and the company’s redemptions appear only in the owner’s activity. The owner’s activity does not include other employees’ earnings, so activity does not add up to the shared balance.

Webhooks

Webhooks identify different users for earning and redeeming. In Partner-Managed Onchain programs, transactionReward.created carries the userId of the employee whose card earned the points. raindrop_redemption.* webhooks carry the company owner’s userId, because every redemption from the shared balance is made by the owner. These webhooks do not include a company ID, so map the owner’s userId to its company in your system.

Concurrent Offchain Redemptions

In Partner-Managed Offchain programs, Rain processes one custom, statement-credit, or travel redemption at a time per company. It checks each request against the company’s shared balance. A redemption request for the company while another is in progress returns 409. Retry after the first request finishes.

The 409 message reads A raindrop redemption is already in progress for this user even when another employee’s request holds the lock, so do not match on the message text. A travel booking retried with the same bookingId while the earlier attempt is still PENDING reuses that redemption instead of returning 409.