Partner-Managed

Integrate Partner-Managed travel redemptions, from the redemption flow to the code recipes.

For Partner-Managed programs, Rain orchestrates travel redemptions against your balance source and fires raindrop_redemption.completed once a booking is confirmed. What you build depends on where your points balances live: Onchain, where you are the source of truth and Rain calls you for balances and burns, or Offchain, where Rain keeps the canonical ledger and you mostly fulfill the booking. This page walks through the flow for both modes and the code recipes that go with each. For shared reference such as status values, API endpoints, and billing, see Travel Redemptions.

Partner-Managed programs skip the Rain-Managed user authorization step. A fresh balance check (webhook for onchain, DB for offchain) is the pre-commit gate before a booking, and there is no raindrop_redemption.created webhook for partner-managed travel redemptions.

Launch the travel portal

Both modes open the travel portal the same way Rain-Managed programs do: in a webview, with an encrypted session token (a JWE) that identifies the cardholder. The token recipe is identical across modes—see Launch the travel portal on the Rain-Managed page.

Rain signs every webhook below with an HMAC SHA256 signature in the Signature header, computed over the exact JSON body using your API key as the secret. Verify it before processing (see How Webhooks Work). Some tenants also receive a version field on redemption webhooks; treat it as optional and ignore any fields you don’t recognize.

Partner-Managed Onchain

Partner Managed (onchain) travel redemption flow

You are the source of truth for points balances, so you implement three handlers: a synchronous balance check Rain calls before a booking, a completion webhook that tells you to burn the points, and a refund webhook that tells you to restore them. All point amounts below are whole points (1 point = $0.01), not native token units.

Balance check

Rain sends a synchronous raindrop_balance.requested webhook whenever the travel portal needs to display or verify a balance. Respond within 1500ms with the cardholder’s spendable balance—confirmed points minus any you’ve already reserved for in-flight redemptions, so the portal can’t double-spend.

Request payload:

{
  "id": "webhook-id",
  "resource": "raindrop_balance",
  "action": "requested",
  "version": "1.0.0",
  "body": {
    "id": "1f2e3d4c-5b6a-7980-1234-567890abcdef"
  }
}

body.id is the cardholder’s Rain user ID.

Your response:

{
  "availableBalance": "2500"
}

availableBalance must be a non-negative integer string of whole points. If your endpoint times out, returns non-2xx, or returns a malformed response, Rain returns 503 to the travel portal.

Booking completion

When a booking is confirmed, Rain fires raindrop_redemption.completed. Acknowledge it immediately, then burn the points in your system out of band. raindropAmount is in whole points—scale it to your token’s native units before burning.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resource": "raindrop_redemption",
  "action": "completed",
  "body": {
    "id": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
    "userId": "1f2e3d4c-5b6a-7980-1234-567890abcdef",
    "type": "TRAVEL_PORTAL",
    "raindropAmount": "2500",
    "bookingId": "booking_abc123"
  }
}

Refund

When a booking is canceled, Rain fires raindrop_redemption.refunded so you re-credit the points. The payload carries no amount, so look up how many points you debited by body.id (the redemption ID from the completion webhook).

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "resource": "raindrop_redemption",
  "action": "refunded",
  "body": {
    "id": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
    "userId": "1f2e3d4c-5b6a-7980-1234-567890abcdef"
  }
}

Webhook listener

A single endpoint handles all three. The balance check responds synchronously; the completion and refund handlers acknowledge first and process out of band.

partnerOnchainWebhookListener.ts

import express from "express";
import { createHmac } from "crypto";

const API_KEY = process.env.RAIN_API_KEY!;
const PORT = Number(process.env.PORT ?? 3000);

function verifyWebhookSignature(rawBody: string, signature: string): boolean {
  const expected = createHmac("sha256", API_KEY).update(rawBody).digest("hex");
  return expected === signature;
}

// You own the ledger. Amounts are whole points (1 point = $0.01).
async function getSpendableBalance(userId: string): Promise<bigint> {
  // Return confirmed points minus points already reserved for in-flight
  // redemptions, so the portal can't double-spend.
  return 0n;
}

async function burnPoints(userId: string, redemptionId: string, points: bigint): Promise<void> {
  // Debit `points` from the user and burn the token onchain. Record the debit
  // immediately so getSpendableBalance() excludes it before the burn confirms.
  // Retry on failure — the booking is already confirmed, so the points must be
  // burned to avoid drift.
}

async function restorePoints(userId: string, redemptionId: string): Promise<void> {
  // Re-credit the points you debited for this redemption. The refund payload
  // has no amount, so resolve it by redemptionId.
}

const app = express();
app.use(express.json({ verify: (req: any, _res, buf) => { req.rawBody = buf.toString(); } }));

app.post("/webhooks", async (req: any, res) => {
  const signature = req.headers["signature"] as string;
  if (!signature || !verifyWebhookSignature(req.rawBody, signature)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { resource, action, body } = req.body;

  // Synchronous balance check — respond within 1500ms.
  if (resource === "raindrop_balance" && action === "requested") {
    const balance = await getSpendableBalance(body.id);
    return res.status(200).json({ availableBalance: balance.toString() });
  }

  // Async events — acknowledge first, then process out of band.
  if (resource === "raindrop_redemption" && action === "completed") {
    res.status(200).json({ ok: true });
    try {
      await burnPoints(body.userId, body.id, BigInt(body.raindropAmount));
    } catch (err) {
      console.error(`Failed to burn points for redemption ${body.id}:`, err);
    }
    return;
  }

  if (resource === "raindrop_redemption" && action === "refunded") {
    res.status(200).json({ ok: true });
    try {
      await restorePoints(body.userId, body.id);
    } catch (err) {
      console.error(`Failed to restore points for redemption ${body.id}:`, err);
    }
    return;
  }

  return res.status(200).json({ ok: true });
});

app.listen(PORT, () => console.log(`Partner webhook listener running on port ${PORT}`));

Delivery is at-least-once, so dedupe on body.id (the redemption ID) before burning or restoring. Burns must be retried until they succeed: the booking is already confirmed, so a dropped burn strands the debit.

Test in sandbox

If your travel portal is not connected yet, stand in for it by calling the travel redemption endpoints yourself in sandbox. Use an Admin key or a custom key with raindrops-travel:read and raindrops-travel:write. Each call triggers the webhooks your listener handles, with the payloads shown in Balance check, Booking completion, and Refund.

1. Check the balance. Call GET /issuing/raindrops/travel-redemptions/balance?userId=<id>. Rain sends raindrop_balance.requested to your endpoint synchronously and waits up to 1500ms. Rain returns your availableBalance as availablePoints.
2. Create a booking. Call POST /issuing/raindrops/travel-redemptions with userId, amount in whole points, a bookingId that starts with sim_, bookingType, totalBookingAmountCents, and bookingDescription. Rain sends raindrop_balance.requested again as a pre-check. If the user has too few points, the call returns 400. If your endpoint does not answer, the call returns 503. Otherwise, Rain skips the travel provider confirmation, marks the redemption COMPLETED, returns 200, and sends raindrop_redemption.completed. Debit the user when the webhook arrives.
3. Refund the booking. Call POST /issuing/raindrops/travel-redemptions/{redemptionId}/refund. Rain marks the redemption REFUNDED, returns 200, and sends raindrop_redemption.refunded. The payload has no amount, so re-credit the user by redemption ID.

Billing still applies in sandbox. Each completed sandbox booking creates a charge for totalBookingAmountCents, plus any redemption premium, on your next sandbox tenant report. A refund reverses the charge.

Once the travel portal is connected, it makes the same calls with real booking IDs. Rain confirms each booking with the travel provider before completing it. Your webhook handlers do not change.

Partner-Managed Offchain

Partner Managed (offchain) travel redemption flow

Rain keeps the canonical points ledger in its database, so it handles balances and refunds for you. There is no balance webhook (Rain reads its own DB) and no refund webhook (Rain restores the DB balance directly). The only travel webhook you receive is raindrop_redemption.completed, and it is informational—Rain has already debited the points by the time it fires. Use it to record the booking or trigger fulfillment in your own system.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resource": "raindrop_redemption",
  "action": "completed",
  "body": {
    "id": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
    "userId": "1f2e3d4c-5b6a-7980-1234-567890abcdef",
    "type": "TRAVEL_PORTAL",
    "raindropAmount": "2500",
    "bookingId": "booking_abc123"
  }
}

partnerOffchainWebhookListener.ts

import express from "express";
import { createHmac } from "crypto";

const API_KEY = process.env.RAIN_API_KEY!;
const PORT = Number(process.env.PORT ?? 3000);

function verifyWebhookSignature(rawBody: string, signature: string): boolean {
  const expected = createHmac("sha256", API_KEY).update(rawBody).digest("hex");
  return expected === signature;
}

async function recordCompletedRedemption(redemptionId: string, userId: string): Promise<void> {
  // Rain already debited its ledger. Record the booking or trigger fulfillment.
}

const app = express();
app.use(express.json({ verify: (req: any, _res, buf) => { req.rawBody = buf.toString(); } }));

app.post("/webhooks", async (req: any, res) => {
  const signature = req.headers["signature"] as string;
  if (!signature || !verifyWebhookSignature(req.rawBody, signature)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Acknowledge first so Rain does not time out.
  res.status(200).json({ ok: true });

  const { resource, action, body } = req.body;
  if (resource === "raindrop_redemption" && action === "completed") {
    try {
      await recordCompletedRedemption(body.id, body.userId);
    } catch (err) {
      console.error(`Failed to record redemption ${body.id}:`, err);
    }
  }
});

app.listen(PORT, () => console.log(`Partner webhook listener running on port ${PORT}`));

To test in sandbox, follow the Onchain walkthrough. Offchain programs get no balance or refund webhook, because Rain checks and restores the balance from its own ledger. You receive only raindrop_redemption.completed.

To debit offchain points for a statement credit, use the statement-credit endpoint.

Webhook summary

Webhook	When It Fires	Mode
raindrop_balance.requested	Travel portal needs balance	Onchain only
raindrop_redemption.completed	Booking confirmed, you should burn	Both
raindrop_redemption.refunded	Refund processed. Restore balance for onchain; informational for offchain.	Onchain only

For onchain partners, raindrop_redemption.completed signals that you should debit or burn points in your system. For offchain partners, Rain has already debited the DB, so the webhook is informational.

Refunds

After the travel portal receives notice from the supplier (for example, a hotel or airline) that a booking was canceled and must be refunded, it sends Rain a message. Rain then re-issues the burned points to the cardholder and marks the redemption REFUNDED. How the restored points settle depends on the mode:

Points Mode	Refund Behavior
Partner-Managed (Offchain)	Rain re-issues the points to the database ledger immediately.
Partner-Managed (Onchain)	Rain fires the raindrop_redemption.refunded webhook so you restore the points in your own system.