PAY.ID — Programmable Payment Policy

Define rules for payments · Enforced on-chain · No server needed

PAY.ID lets you control who can pay you, how much, and under what conditions — enforced automatically on-chain.

Use cases:

• Only accept stablecoins (USDC, USDT)
• Set spending limits ($10–$500)
• Require KYC verification
• Block payments from blacklisted addresses
• Time-based policies (business hours only)

---

Quick Start: What do you want to do?

I want to...	Start here
Test a payment (pay someone)	Simple Usage → — 5-minute test
Integrate into my dApp	Quick Start → — React or Node.js
Set up payment rules (receive payments)	Quick Start → — Merchant setup
Understand how it works	Core Concepts → — Deep dive

---

How It Works

Context → Rules (WASM engine) → Decision → Proof (EIP-712) → On-chain Verify

Step	What Happens
Context	Payment details: who's paying, what token, how much, when
Rules	Your rules evaluated in a WASM sandbox — deterministic, auditable
Decision	ALLOW ✅ or REJECT ❌
Proof	If ALLOW, an EIP-712 signed proof is generated (payer signs with their wallet)
Verify	Smart contract checks the proof, then executes the transfer or reverts

The contracts never run your rules on-chain — they only verify the signed proof. This keeps gas costs low.

---

Choose Your Integration Path

Path A — React / Frontend (payid-react)

Install one package, wrap your app in a provider, and use a single hook. Recommended for most dApps.

import { usePayIDFlow } from 'payid-react'

function CheckoutButton() {
  const { execute, status, txHash } = usePayIDFlow()

  return (
    <button onClick={() => execute({
      receiver: '0xMerchant...',
      asset:    '0xUSDC...',
      amount:   50_000_000n,       // 50 USDC
      payId:    'pay.id/my-store',
    })}>
      {status === 'idle'    && 'Pay 50 USDC'}
      {status === 'proving' && 'Sign in wallet...'}
      {status === 'success' && '✅ Paid!'}
    </button>
  )
}

→ React Quick Start →

---

Path B — Node.js / Backend (payid)

For servers, APIs, automated bots, and ERC-4337 bundlers. The server wallet signs proofs.

import { createPayIDServer } from 'payid/server'
import { Wallet } from 'ethers'

const payid = createPayIDServer({
  signer: new Wallet(process.env.PRIVATE_KEY!),
})

const { result, proof } = await payid.evaluateAndProve({
  context, payId, payer, receiver, asset, amount,
  verifyingContract, ruleAuthority, chainId, blockTimestamp,
})

→ Server Guide →

---

The 4 Core Concepts

🪪 1. Payment Identity (pay.id/yourname)

Not just a wallet address — it carries your payment rules. When someone pays pay.id/my-store, PAY.ID automatically fetches and evaluates the rules attached to that identity.

📋 2. Rules (JSON configs)

Rules define your payment policy. They are stored on IPFS with their hash committed on-chain. Three formats: SimpleRule, MultiConditionRule, NestedRule. → Rule Basics →

🔐 3. Decision Proof (EIP-712)

Every approved payment generates a cryptographic receipt signed by the payer's own wallet. No trusted third party needed — the blockchain verifies it.

⛓️ 4. On-chain Enforcement

Smart contracts verify the proof (never execute rules). This keeps contracts simple and cheap to audit.

---

What PAY.ID Is NOT

❌ Not	✅ But
A wallet	A policy layer for payments
A payment gateway	A cryptographic proof generator
A custodian	An identity + rules protocol
A blockchain or L2	Works on any EVM chain

---

Packages

Package	Description	Install
payid	Core SDK — rule engine, proof generation	npm i payid ethers
payid-react	React hooks — wallet integration	npm i payid-react wagmi viem ethers

---

What's New

• 🔗 Platform × PAY.ID Bridge — Seamlessly blend any platform's milestone escrow with PAY.ID's reputation & policy layer. Composite scoring, policy-gated escrow, and one-liner setup.
• 🔌� Platform Adapters — Plug in your own reputation/escrow system or unplug PAY.ID's defaults. Perfect for platforms that already have MilestoneManager and ReputationContract.
• �🛡️ VRAN Reputation — Decentralized trust layer. Check merchant reputation and blacklist status before paying.
• 🏦 Bank / QRIS Bridge — Use PAY.ID as a policy oracle for fiat payment rails (QRIS, SWIFT, SEPA).
• ⚙️ Configurable Storage Resolver — Override the storage indexer URL via SDK options instead of global variables.

---

Live Testnets

Choose a testnet to start building:

Network	Chain ID	Currency	Faucet
Arbitrum Sepolia	421614	ETH	Get ETH →
0G Galileo	16602	A0GI	Get A0GI →
Sepolia	11155111	ETH	Get ETH →
Base Sepolia	84532	ETH	Get ETH →
Polygon Amoy	80002	MATIC	Get MATIC →

Contract addresses: See full list →

---

Getting Started

New to PAY.ID? Start here:

Step	Link
1. Test a payment in 5 minutes	� Simple Usage →
2. Integrate into your app	⚡ Quick Start →
3. Learn how rules work	📋 Rule Basics →

Already familiar?

Goal	Link
All React hooks (20+)	⚛️ React Integration →
Backend / Node.js	🖥️ Server Guide →
Core concepts deep dive	📖 Core Concepts →