Travel Redemptions

Enable cardholders to book travel using their Raindrops at full face value.

Travel redemptions let cardholders book flights, hotels, car rentals, packages, tickets, and VIP experiences using their points at full face value (1 point = $0.01).

This requires integration between your app, Rain, and our white-label travel portal provider. What you build depends on your points mode. Pick the page that matches your program type. Each one covers the end-to-end flow and the code you write in one place.

Rain Managed

Rain orchestrates the redemption and fires raindrop_redemption.created so you can burn the points. Covers the flow plus the portal-launch and webhook recipes.

Partner Managed

Rain uses your balance source (onchain or offchain) and fires raindrop_redemption.completed. Covers both modes plus the balance, completion, and refund recipes.

Who Builds What

Party	Responsibilities
Your app	Opens the travel portal in a webview, passing an encrypted JWT. Subscribes to redemption webhooks. Enforces points burning for onchain programs.
Travel provider	Decodes the session JWT, fetches the user’s travel balance from Rain, posts redemption requests on booking, and exposes an HMAC-signed callback for Rain to confirm bookings.
Rain	Orchestrates the redemption lifecycle, confirms bookings with the travel provider, emits webhooks, and processes refunds.

Redemption Status Values

Status	Description
PENDING	Redemption requested, awaiting user authorization or partner-managed booking confirmation retry
PROCESSING	User authorized, Rain-Managed burn in progress
COMPLETED	Booking finalized
FAILED	Burn or booking failed
REFUNDED	Manual refund processed

API Endpoints

Use these endpoints to manage travel redemptions.

Endpoint	Description
GET /issuing/raindrops/travel-redemptions/balance	Get the user’s travel-redemption balance (availablePoints)
POST /issuing/raindrops/travel-redemptions	Reserve points for a booking. Returns 201 PENDING for Rain-Managed and 200 COMPLETED for Partner-Managed when the booking is confirmed.
POST /issuing/raindrops/travel-redemptions/{redemptionId}/refund	Refund a completed redemption. Called by the travel partner on behalf of the tenant when a booking falls through.

In a corporate program, only the company owner can book with points. A booking request for any other employee returns 403. In Rain-Managed and Partner-Managed Offchain programs, the balance endpoint returns the company’s shared balance for any employee. In Partner-Managed Onchain programs, Rain asks your system for the balance of the employee in the request, so return the company’s shared balance. See Corporate Programs.

The refund endpoint is safe to retry. The first call on a COMPLETED redemption restores the points and marks it REFUNDED; a later retry on the same redemption returns 200 with REFUNDED again rather than refunding twice. Two refunds racing in parallel return 409 for the loser. A 404 means the redemption does not exist or is not in a refundable state (for example, it never reached COMPLETED).

An Admin API key covers the raindrops-travel scope, so it can call every travel redemption endpoint. A custom API key for your travel portal needs raindrops-travel:read to display balances and raindrops-travel:write to create or refund redemptions. In production, Rain issues an API key scoped to raindrops-travel for your travel portal integration.

Test in sandbox

To test your webhook handlers before the travel portal is connected, create simulated bookings in sandbox. Call POST /issuing/raindrops/travel-redemptions with a sandbox API key: either an Admin key or a custom key with raindrops-travel:write. Pass a bookingId that starts with sim_, such as sim_test-booking-1. Rain treats a sim_ booking as confirmed without contacting the travel provider. What happens next depends on your program type:

• Partner-Managed: The call returns 200 with status COMPLETED, and Rain sends raindrop_redemption.completed. For a step-by-step walkthrough, see Test in sandbox on the Partner-Managed page.
• Rain-Managed: The call returns 201 with status PENDING, and Rain sends raindrop_redemption.created. When the cardholder authorizes the burn, Rain skips the travel provider confirmation for the sim_ booking. The redemption completes after the onchain burn. Rain-Managed programs do not receive a raindrop_redemption.completed webhook.

Every other step runs as it does for a real booking:

• Rain checks the cardholder’s balance before it creates the redemption. For Partner-Managed Onchain programs, this check sends raindrop_balance.requested to your endpoint.
• To test your refund handling, call POST /issuing/raindrops/travel-redemptions/{redemptionId}/refund on the completed redemption.
• Each bookingId must be unique, so use a new sim_ ID for each test. Reusing an ID returns 409.

In production, the sim_ prefix has no special handling, and Rain asks the travel provider to confirm every booking.

Billing Impact

Rain charges the booking’s face value, plus any redemption premium, on your next tenant report after the travel redemption completes. The charge comes from the redemption, not from minting. If you refund the booking before that report, Rain drops the charge. If the report already includes it, Rain adds a matching credit that a later report absorbs.