All projects

N9/08AI & agentsFintechComplexity: Advanced

PayPal Attribute

When an AI shopping agent recommends a product, the creators it cited get a fair share of the sale, paid through PayPal.

Status
Live demo (sandbox)
Year
2026
Built for
Hackathon prototype on the PayPal developer platform
Languages
TypeScript, CSS, JavaScript
Team
Sujal Negi
01

Overview

“Every AI answer has sources. Now every source gets paid.” PayPal Attribute is an attribution and payout rail for agentic commerce. A shopping agent cites the reviews, guides and videos that shaped its answer; the citations travel inside the PayPal order; when the payment is captured, AI scores how much each source influenced the purchase, risk checks remove fraud, and the commission is split and paid to creators through PayPal Payouts.

It is a hackathon prototype, not an official PayPal product, and runs in the PayPal sandbox where no real money moves.

02

Problem and aim

Problem

When an AI agent gives a single answer, there are no clicks and no affiliate links. Creators whose work made the answer trustworthy lose the income that funds them, and merchants cannot see what drove a sale.

Aim

Make AI recommendations pay the people behind them, fairly and safely, using rails PayPal already has.

03

How it works

01 / 05

Ask the agent

A shopper asks what to buy. Retrieval runs in code; the model writes a grounded answer where every claim has a footnote to a real creator source.

02 / 05

Token in the order

An attribution token rides inside the PayPal order (custom_id) and is verified when the payment is captured.

03 / 05

Score influence

AI scores how much each cited source influenced the purchase, blended 75/25 with a deterministic baseline so one model answer cannot swing payouts.

04 / 05

Risk checks

Six checks on every sale: self-dealing, blocked sources, citation stuffing, merchant budget, purchase velocity and the attribution window.

05 / 05

Split and pay

The commission minus a 10% network fee is split by influence, held through the return window, then paid via PayPal Payouts. Refunds reverse or claw back payouts.

04

Architecture

One Next.js service for UI, API and the money engine

AWho uses it

  • ShopperChats with the agent at /shop and pays with PayPal.
  • Merchants and creatorsLedgers, rules, earnings.
  • Other AI agentsREST API at /api/v1 or the MCP server.

BNext.js 15 service

  • Agent + scoringGrounded answers; AI influence scores.
  • EngineRisk checks, split, hold window, ledger.
  • API routescheckout, webhook, payouts, refunds, v1.

CData and services

  • Document storeAtomic JSON store, swappable for Postgres.
  • PayPal sandboxOrders, Payouts, Webhooks, Log in with PayPal.
  • AI chainGroq → Gemini → built-in rules.

Request flow

  1. The agent answers with citations; an attribution token is created for them.
  2. Checkout creates a PayPal order carrying the token in custom_id.
  3. On capture (and the verified webhook), influence is scored and risk checks run.
  4. The pool is split to the cent and held; releaseDuePayouts() pays via PayPal Payouts.
05

Languages and code

  • TypeScript86.4%
  • CSS12.5%
  • JavaScript1.1%

Repository

82 files7,201 linesTap any file to read its code

  • docs/1 file
    • 26 lines
  • mcp/1 file
    • MCP server so any agent can make recommendations attributable. 105 lines
  • public/1 file
    • 1 line
  • src/66 files
    • app/Pages (shop, attribution trace, merchants, creators, developers, risk) and all API routes.
      • api/26 files
        • agent/1 file
          • chat/1 file
            • 45 lines
        • ai/1 file
          • check/1 file
            • 23 lines
        • apps/1 file
          • 22 lines
        • auth/1 file
          • paypal/1 file
            • callback/1 file
              • 30 lines
        • checkout/3 files
          • capture/1 file
            • 29 lines
          • order/1 file
            • 36 lines
          • simulate/1 file
            • 31 lines
        • creators/2 files
          • [id]/2 files
            • connect/1 file
              • 28 lines
            • sources/1 file
              • 25 lines
        • demo/1 file
          • reset/1 file
            • 13 lines
        • health/1 file
          • 7 lines
        • merchants/2 files
          • [id]/2 files
            • insights/1 file
              • 85 lines
            • 32 lines
        • payouts/1 file
          • release/1 file
            • 17 lines
        • paypal/1 file
          • webhook/1 file
            • 73 lines
        • risk/1 file
          • [id]/1 file
            • 48 lines
        • sales/2 files
          • [id]/2 files
            • refund/1 file
              • 24 lines
            • 17 lines
        • status/1 file
          • 14 lines
        • v1/7 files
          • attributions/2 files
            • [token]/1 file
              • 23 lines
            • 68 lines
          • creators/1 file
            • [id]/1 file
              • earnings/1 file
                • 28 lines
          • openapi.json/1 file
            • 8 lines
          • postman.json/1 file
            • 11 lines
          • sales/1 file
            • [id]/1 file
              • 19 lines
          • sources/1 file
            • 55 lines
      • attribution/3 files
        • [id]/2 files
          • 17 lines
          • 384 lines
        • 78 lines
      • creators/2 files
        • 305 lines
        • 67 lines
      • developers/2 files
        • 425 lines
        • 26 lines
      • merchants/2 files
        • 267 lines
        • 83 lines
      • risk/2 files
        • 19 lines
        • 112 lines
      • shop/2 files
        • 22 lines
        • 447 lines
      • 182 lines
      • 31 lines
      • 254 lines
      • 2 lines
    • components/Shared UI: answer with footnotes, PayPal buttons, data grid.
      • 97 lines
      • 56 lines
      • 91 lines
      • 83 lines
      • 21 lines
      • 163 lines
    • lib/The core.
      • The shopping agent and the model fallback chain. 228 lines
      • The shopping agent and the model fallback chain. 187 lines
      • 86 lines
      • The public API spec and the optional live catalogue. 78 lines
      • Capture → score → risk → split → hold → payout, and refunds. 383 lines
      • 46 lines
      • The public API spec and the optional live catalogue. 152 lines
      • Orders, capture, payouts, refunds and webhook verification. 205 lines
      • Deterministic baseline scores and the six risk checks. 82 lines
      • Deterministic baseline scores and the six risk checks. 82 lines
      • Persistence and 30 days of history made by the real engine. 174 lines
      • Commission, fee, min/max shares, largest-remainder rounding. 113 lines
      • Persistence and 30 days of history made by the real engine. 72 lines
      • 270 lines
      • 81 lines
      • 91 lines
  • tests/Engine, payout and split tests.
    • 81 lines
    • 69 lines
    • 70 lines
  • 28 lines
  • 11 lines
  • 21 lines
  • 10 lines
  • 47 lines
  • 2 lines
  • 248 lines
  • One-click deployment on Render. 36 lines
  • 21 lines
  • 7 lines
06

Methodology

  1. Keep money in integer cents and write every movement to an append-only ledger.
  2. Round shares with the largest-remainder method so payouts always add up exactly.
  3. Use a fallback chain of free models (Groq, then Gemini, then built-in rules) so the product works with no keys at all.
  4. Seed 30 days of history by running the real engine on simulated orders.
07

Technology

AppNext.js 15 + TypeScriptOne service for UI and API.
PayPalOrders v2 + Smart ButtonsCheckout inside the agent.
Payouts v1Pays creators in one batch.
Webhooks + Log in with PayPalVerified events and creator accounts.
AI and dataGroq → Gemini → rulesFree-tier fallback chain, validated with zod.
AG Grid + AG ChartsMerchant and creator ledgers.
MCP serverAny agent can integrate without custom code.
08

Demo

09

Concepts

01What is attribution?

Working out which sources caused a sale. Affiliate links do it with clicks; here the AI’s own citations are the evidence.

02Why store money in cents?

Decimal fractions cannot be stored exactly in floating point, so totals drift. Whole numbers of cents never do.

03What is largest-remainder rounding?

Give everyone the rounded-down amount, then hand the leftover cents one by one to whoever had the biggest fractions. The shares always add up to the exact pool.

04Why a hold window?

Buyers can return products. Waiting until the return window closes means creators are not paid for sales that get refunded.

10

Team