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

# Travel Redemptions

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

Travel redemptions let cardholders book flights, hotels, car rentals, and packages 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.

<Card title="Rain Managed" icon="plane" href="/docs/rewards/redemptions/travel-redemptions/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.
</Card>

<Card title="Partner Managed" icon="plane" href="/docs/rewards/redemptions/travel-redemptions/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.
</Card>

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

<Warning>
  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`).
</Warning>

<Info>
  Travel portal API keys need `raindrops-travel:read` for balance display and `raindrops-travel:write` for create/refund calls.
</Info>

## Billing Impact

The booking's face value is charged on your next tenant report when the travel redemption completes. Charges are created at redemption time by default, not at mint or DB finalization time. A refund inserts a compensating credit.