Roochip Lite — Integration Guide

What is Roochip Lite?

Roochip Lite is a standalone B2B credit issuing platform. Rooverse does not own any payment processing, credit storage, or ledger logic. Instead, Rooverse calls Roochip’s REST API and receives credit events via signed webhooks.

Think of Roochip Lite as the credit bank. Rooverse is the app that uses it. Users never interact with Roochip directly — they see only the Rooverse UI.

The ROO Currency

One unified wallet

Purchased ROO and earned ROO are the same currency in one wallet. There is no distinction between “bought credits” and “reward credits” in the balance — only the ledger history records how credits were obtained.

How to display ROO in the UI

System Architecture

How all the components connect:

Key principle

When a user pays, money goes to Roochip Lite’s payment accounts. Roochip is the merchant of record. Rooverse has zero payment compliance obligations for ROO purchases.

Rollout Phases

User Wallet & Balance

Every Rooverse user has exactly one ROO wallet, managed entirely by Roochip Lite. The wallet is created automatically on the first API call for that user — Rooverse does not need to explicitly register users.

Where the balance lives

When to refresh the displayed balance

• On wallet screen open — fetch live from API
• After receiving a credits.issued webhook — update cache with new_balance
• After a successful deduct call — use new_balance from response
• After a successful reward call — use new_balance from response
• After promo code redemption — use new_balance from response

Wallet screen — what to show

Earning ROO — Reward System

Users earn ROO by performing actions inside Rooverse. Rooverse owns all reward rules — Roochip has no knowledge of triggers, caps, or amounts. Rooverse applies its own logic before calling the reward API.

Suggested reward values

These are suggestions only. Rooverse controls the amounts, triggers, and caps entirely.

Anti-abuse implementation pattern

// Rooverse backend pseudocode
async function handleLikeEvent(userId, postId) {
  // 1. Rooverse rules check
  const todayLikes = await db.countRewardsToday(userId, 'like');
  if (todayLikes >= 50) return;
  const alreadyRewarded = await db.rewardExists(userId, postId, 'like');
  if (alreadyRewarded) return;

  // 2. Only now call Roochip
  await roochip.post(`/v1/users/${userId}/reward`, {
    credits: 0.01,
    reason: 'like',
    reference_id: postId
  });
}

Spending ROO — Paid Features

When a user activates a paid feature, the Rooverse backend calls the deduct API. Credits are deducted atomically — PostgreSQL row-level locking prevents concurrent overdrafts.

Example feature costs

Deduct-then-run pattern

async function runAIGeneration(userId, jobId) {
  const COST = 10.00;

  // 1. Deduct first (atomic, row-locked)
  const result = await roochip.post(`/v1/users/${userId}/deduct`, {
    credits: COST,
    reason: 'ai_generation',
    reference_id: jobId
  });

  if (result.status === 402) {
    return { error: 'insufficient_credits', required: COST };
  }

  // 2. Credits confirmed deducted - now run the feature
  await runAIJob(jobId);

  // 3. Update Rooverse UI cache
  await db.users.update({ roochip_balance: result.data.new_balance }, userId);
}

Buying ROO — Purchase Flow

Users top up their ROO wallet by purchasing credit packages. Packages are defined and priced by Roochip Lite. Rooverse fetches and displays them — it never sets prices or creates packages.

Available packages (current seed data)

Phase 1 — “Coming soon” response

Until Stripe is configured, POST /v1/checkout returns:

HTTP 503
{
  "status": "coming_soon",
  "message": "Payment system coming soon! In the meantime, request a free 5-credit code.",
  "request_code_endpoint": "POST /v1/codes/request"
}

Display this message and show a “Request a free code” button immediately below it.

Phase 2 — Real checkout (future)

POST /v1/checkout will return a checkout_url. Web: open in in-app WebView. Mobile: use native IAP (see Payment Methods).

Payment Methods

Why mobile must use native IAP

Apple and Google require that in-app purchases of digital goods go through their own payment systems — not Stripe. The Rooverse mobile app sends the receipt / purchase token to the Rooverse backend, which forwards it to Roochip for server-side verification and credit issuance.

Mobile IAP call (from Rooverse backend)

// iOS: after successful StoreKit purchase
const response = await fetch('https://nevis-credit-system-test.vercel.app/iap/apple', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ROOCHIP_API_KEY },
  body: JSON.stringify({
    external_user_id: userId,
    receipt_data: appleReceiptBase64,  // from StoreKit
    package_id: selectedPackage.id,
    tenant_id: TENANT_ID
  })
});
// Roochip verifies with Apple, issues credits, fires webhook

Ownership Boundaries

Authentication

All Rooverse → Roochip calls are server-to-server only. Never call the Roochip API from frontend JavaScript, React Native bundles, or a WebView.

X-API-Key: rc_test_rooverse_key_123   <!-- test key; replace with production key for live -->

Environment Variables (Rooverse backend)

# Provided by Roochip Lite during onboarding
ROOCHIP_API_KEY=rc_test_rooverse_key_123   # replace with production key for live
ROOCHIP_BASE_URL=https://nevis-credit-system-test.vercel.app
ROOCHIP_WEBHOOK_SECRET=roochip_provided_secret

Phase 1: Promo Code Flow

POST /v1/codes/request
{ "external_user_id": "rooverse-user-123" }

POST /v1/codes/redeem
{ "external_user_id": "rooverse-user-123", "code": "ROO-A3F29C1B" }

Promo Code UI — What to Build

Wallet / Buy screen

After requesting a code

On success → “Your request has been received. We’ll send you a code soon.”
On 409 → “You’ve already submitted a request. Check your messages for your code.”

Promo Code Endpoints

// Request
{ "external_user_id": "rooverse-user-123" }

// 201 Success
{ "message": "Request received. An admin will generate your code shortly.", "status": "pending" }

// 409 Already requested
{ "error": "You have already requested a promo code. Each account can only request once." }

// Request
{ "external_user_id": "rooverse-user-123", "code": "ROO-A3F29C1B" }

// 200 Success
{ "message": "5 ROO credits added to your account.", "credits_issued": 5, "new_balance": 5 }

{
  "requests": [
    { "id": "uuid", "external_user_id": "rooverse-user-123", "status": "pending", "created_at": "..." }
  ],
  "count": 1
}

// Request
{ "external_user_id": "rooverse-user-123" }

// 201 Success
{
  "code": "ROO-A3F29C1B",
  "external_user_id": "rooverse-user-123",
  "credits": 5,
  "message": "Share this code with rooverse-user-123. It is single-use."
}

Get Available Packages

{
  "packages": [
    { "id": "uuid", "name": "Starter Pack",  "credits_to_issue": 10, "price_amount": 1000, "currency": "usd" },
    { "id": "uuid", "name": "Popular Pack",  "credits_to_issue": 25, "price_amount": 2500, "currency": "usd" },
    { "id": "uuid", "name": "Premium Pack",  "credits_to_issue": 50, "price_amount": 5000, "currency": "usd" }
  ]
}

Get User Balance

{ "external_user_id": "rooverse-user-123", "balance": 115.50, "updated_at": "2026-03-30T10:00:00Z" }

Get Transaction History

{
  "external_user_id": "rooverse-user-123",
  "total": 3, "page": 1, "limit": 20,
  "entries": [
    { "type": "purchase",  "credits_delta":  120.00, "balance_before":   0, "balance_after": 120.00, "created_at": "..." },
    { "type": "reward",    "credits_delta":    0.01, "balance_before": 120, "balance_after": 120.01, "created_at": "..." },
    { "type": "deduction", "credits_delta":  -10.00, "balance_before": 120.01, "balance_after": 110.01, "created_at": "..." }
  ]
}

Deduct Credits

// Request
{ "credits": 10.00, "reason": "ai_generation", "reference_id": "rooverse-job-abc123" }

// 200 Success
{ "external_user_id": "rooverse-user-123", "credits_deducted": 10.00, "new_balance": 110.00 }

// 402 Insufficient credits
{ "error": "Insufficient credits" }

Issue a Reward

// Request
{ "credits": 0.01, "reason": "like", "reference_id": "post-uuid-abc" }

// 200 Success
{ "external_user_id": "rooverse-user-123", "credits_rewarded": 0.01, "new_balance": 120.01 }

Inbound Webhooks — Roochip → Rooverse

After any credit issuance (purchase, IAP, promo, reward), Roochip POSTs to your webhook URL:

POST https://rooverse.app/webhooks/roochip

Webhook payload

{
  "event": "credits.issued",
  "external_user_id": "rooverse-user-123",
  "credits_issued": 120.00,
  "new_balance": 320.00,
  "payment_source": "stripe",
  "timestamp": "2026-03-30T10:00:00Z"
}

payment_source: stripe | apple_iap | google_iap | promo_code

What Rooverse must do on receipt

Webhook Signature Verification

const crypto = require('crypto');

function verifyRoochipWebhook(req, secret) {
  const signature = req.headers['x-roochip-signature'];
  if (!signature) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(req.body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

app.post('/webhooks/roochip', express.json(), async (req, res) => {
  if (!verifyRoochipWebhook(req, process.env.ROOCHIP_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const { event, external_user_id, credits_issued, new_balance, payment_source } = req.body;
  if (event === 'credits.issued') {
    await db.users.update({ roochip_balance: new_balance }, { where: { id: external_user_id } });
    await db.roochipEvents.create({ event, external_user_id, credits_issued, new_balance, payment_source });
  }
  res.sendStatus(200);
});

Rooverse Database Changes Required

These are the only database changes Rooverse needs. All wallet logic lives in Roochip’s database.

1. Cached balance column (required)

ALTER TABLE users
  ADD COLUMN IF NOT EXISTS roochip_balance NUMERIC(12,2) NOT NULL DEFAULT 0;

CREATE INDEX IF NOT EXISTS idx_users_roochip_balance ON users(roochip_balance);

2. Event log table (required)

CREATE TABLE IF NOT EXISTS roochip_events (
  id               UUID          PRIMARY KEY DEFAULT gen_random_uuid(),
  external_user_id TEXT          NOT NULL,
  event            TEXT          NOT NULL,                 -- 'credits.issued'
  credits_issued   NUMERIC(12,2),
  new_balance      NUMERIC(12,2),
  payment_source   TEXT,                                   -- stripe|apple_iap|google_iap|promo_code
  raw_payload      JSONB,                                  -- full webhook body
  received_at      TIMESTAMPTZ   NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS idx_roochip_events_user ON roochip_events(external_user_id);
CREATE INDEX IF NOT EXISTS idx_roochip_events_time ON roochip_events(received_at DESC);

3. Code request flag (recommended)

ALTER TABLE users
  ADD COLUMN IF NOT EXISTS roochip_code_requested BOOLEAN NOT NULL DEFAULT FALSE;

Set to TRUE when the user taps “Request Code”. Hides the button and shows “Code requested — check your messages” on subsequent visits.

Summary

Buy Flow — Future (Phase 2)

Spend Credits Flow

Reward Flow

Error Codes

What Rooverse Does NOT Need to Build

• Stripe integration of any kind
• Apple IAP receipt verification
• Google IAP purchase token verification
• Credit wallet or ledger tables
• Double-payment prevention logic
• Credit package pricing or management
• Promo code generation or storage
• One-request-per-user enforcement for promo codes
• Webhook retry logic (Roochip retries automatically)
• Currency precision handling (Roochip stores as NUMERIC(12,2))