Payment & Reward Flow

This document describes how points and referee rewards are handled in Peppercheck.

1. Prerequisites

  • Task Lifecycle — Point lock occurs at task creation, settlement at judgement confirmation.

  • Subscription — Subscriptions grant monthly points.

Implementation Status

Currently implemented:

  • Subscription purchases (Web via Stripe Checkout, Mobile via Google IAP)

  • Point system (grant via subscription, lock at task creation, settle on confirm)

  • Reward system — internal tracking (reward_wallets, reward_ledger)

Planned / Not yet implemented:

  • Stripe Connect for Referee payouts

  • Reward transfers to Referee Stripe balance

  • Automatic monthly bank payouts

2. Overview

  • Tasker purchases subscriptions, which grant monthly points.

  • Tasker locks points when creating tasks (requesting reviews); points are settled on judgement confirmation.

  • Referee completes reviews and earns rewards (tracked internally; Stripe Connect payouts planned).

UX copy shows "Tasker pays Referee directly", but legally Peppercheck collects payments first and pays Referees as contractors (marketplace model).

3. Operational Flow

Diagram

4. Point Lock / Settle Mechanism

Points follow a two-phase model to ensure funds are reserved but not consumed until the review process completes.

4.1. Phases

  1. Lock — When a Task is opened, points are locked in the Tasker’s wallet via lock_points(). The locked column on point_wallets increases; the wallet balance is unchanged. Available balance = balance - locked.

  2. Settle — When a Judgement is confirmed (or evidence times out), locked points are consumed via consume_points(). Both balance and locked decrease.

  3. Unlock (failure path) — If a matching fails, locked points are returned via unlock_points(). The locked column decreases; balance remains unchanged.

4.2. Database Functions

Function Description

lock_points(p_user_id, p_amount, p_reason, p_description, p_related_id)

Lock points in the wallet. Raises exception if available (balance - locked) is insufficient.

unlock_points(p_user_id, p_amount, p_reason, p_description, p_related_id)

Release locked points back to available. Raises exception if locked amount is insufficient.

consume_points(p_user_id, p_amount, p_reason, p_description, p_related_id)

Settle: deduct from both balance and locked. Raises exception if either is insufficient.

4.3. Point Reasons (point_reason enum)

Relevant values for the lock/settle flow:

  • matching_lock — Points locked at task creation

  • matching_unlock — Points returned on failure

  • matching_settled — Points consumed at judgement confirmation

5. Reward System (Internal)

Referee rewards are currently tracked internally. Stripe Connect payouts are planned but not yet implemented.

5.1. reward_wallets Table

Column Type Description

user_id

uuid (PK, FK → auth.users)

Referee user ID

balance

integer

Current reward balance (≥ 0)

created_at / updated_at

timestamptz

Timestamps

5.2. reward_ledger Table

Column Type Description

id

uuid (PK)

Ledger entry ID

user_id

uuid (FK → auth.users)

Referee user ID

amount

integer

Reward amount

reason

reward_reason (enum)

Reason for the entry

description

text

Optional description

related_id

uuid

Related entity ID (e.g. judgement ID)

created_at

timestamptz

Timestamp

5.3. Reward Reasons (reward_reason enum)

  • review_completed — Reward for completing a review

  • evidence_timeout — Reward when tasker fails to submit evidence

  • payout — Stripe Connect payout (planned)

  • manual_adjustment — Manual adjustment by admin

5.4. grant_reward() Function

Upserts reward_wallets (creates if not exists) and inserts a reward_ledger entry.

Parameters: p_user_id, p_amount, p_reason, p_description, p_related_id.

6. Stripe Connect (Planned)

When implemented, Peppercheck will use Stripe Connect to pay Referees:

  • Account Type: Express or Custom accounts

  • Charge Model: Separate Charges & Transfers

  • Reward Transfer: Per completed review, from Platform to Referee Stripe balance

  • Payouts: Monthly automatic payout from Referee Stripe balance to bank account