Skip to main content
skill CX Codex

payment-application-processor — Claude Code skill

payment-application-processor — a skill that processes construction payment applications: validates schedule of values, calculates retainage, tracks payment status, and generates G702/G703 forms. Requires Python 3.

MIT 117 installs ★ 434 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill payment-application-processor -a claude-code
Open on GitHub

What payment-application-processor does

This skill automates the full payment application cycle from draft to approval. You enter a schedule of values, record completed work and stored materials, and the skill computes percent complete, retainage amounts based on your rates, and net payment due. It supports contract changes through change orders.

Internally, it manages payment application objects with full status tracking (draft, submitted, under review, approved, paid). It carries forward previous totals from prior applications to calculate cumulative earned amounts and remaining balance. Requires python3 on your system.

What it helps with

  • validate payment applications against schedule of values
  • calculate retainage and net amount due
  • track payment status from creation through payment
  • generate G702 data for AIA forms

Example prompts for the agent

  • Create payment application #5 with 50000 completed work and 10% retainage
  • Add foundation line to schedule of values: 100000
  • Import 20 schedule items from CSV and calculate totals

How to install payment-application-processor

1Skills CLI (Vercel)

npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill payment-application-processor -a claude-code

2Manually: put the files in place

~/.claude/skills/payment-application-processor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/payment-application-processor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about payment-application-processor

How do I install payment-application-processor in Claude Code?

Run npx skills add datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction --skill payment-application-processor -a claude-code, then open ~/.claude/skills/payment-application-processor/SKILL.md.

What does payment-application-processor do?

The skill manages construction payment applications: stores a schedule of values, calculates retainage at your chosen rate, tracks payment status across its lifecycle, and generates data for standard G702/G703 forms.

What are the system requirements?

You need python3. The skill runs on macOS, Linux, and Windows.

Source text

SKILL.md · MIT
---
name: "payment-application-processor"
description: "Process construction payment applications. Validate schedule of values, calculate retainage, track billing status, and generate G702/G703 forms."
homepage: "https://datadrivenconstruction.io"
metadata: {"openclaw": {"emoji": "💵", "os": ["darwin", "linux", "win32"], "homepage": "https://datadrivenconstruction.io", "requires": {"bins": ["python3"]}}}
---
# Payment Application Processor

## Overview

Process construction payment applications from creation through approval. Validate against schedule of values, calculate retainage, generate AIA G702/G703 forms, and track payment status.

## Payment Application Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                PAYMENT APPLICATION FLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Schedule of    →    Draft      →    Review    →    Approve    │
│  Values              Pay App         & Verify        & Pay      │
│  ──────────          ───────         ────────        ────────   │
│  📋 SOV items        📝 Enter %      ✓ Verify        ✅ Approve │
│  💰 Line values      📊 Calculate    📸 Field        💵 Release │
│  📅 Billing plan     📄 G702/703     📧 Submit       📄 Record  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Technical Implementation

```python
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from datetime import datetime, timedelta
from enum import Enum

class PayAppStatus(Enum):
    DRAFT = "draft"
    SUBMITTED = "submitted"
    UNDER_REVIEW = "under_review"
    APPROVED = "approved"
    REJECTED = "rejected"
    PAID = "paid"
    PARTIAL_PAID = "partial_paid"

class LineItemStatus(Enum):
    NOT_STARTED = "not_started"
    IN_PROGRESS = "in_progress"
    COMPLETE = "complete"

@dataclass
class SOVLineItem:
    number: str
    description: str
    scheduled_value: float
    previous_completed: float = 0.0
    current_completed: float = 0.0
    materials_stored: float = 0.0
    percent_complete: float = 0.0
    balance_to_finish: float = 0.0
    retainage: float = 0.0

    def calculate(self, retainage_rate: float = 0.10):
        """Calculate line item values."""
        self.percent_complete = (
            (self.previous_completed + self.current_completed + self.materials_stored)
            / self.scheduled_value * 100
            if self.scheduled_value > 0 else 0
        )
        self.balance_to_finish = (
            self.scheduled_value - self.previous_completed -
            self.current_completed - self.materials_stored
        )
        total_completed = self.previous_completed + self.current_completed + self.materials_stored
        self.retainage = total_completed * retainage_rate

@dataclass
class PaymentApplication:
    application_number: int
    project_name: str
    contractor: str
    period_from: datetime
    period_to: datetime

    # Contract info
    original_contract: float
    change_orders: float = 0.0
    contract_sum: float = 0.0

    # Line items
    line_items: List[SOVLineItem] = field(default_factory=list)

    # Totals
    total_scheduled: float = 0.0
    previous_completed: float = 0.0
    current_completed: float = 0.0
    materials_stored: float = 0.0
    total_completed: float = 0.0
    percent_complete: float = 0.0
    balance_to_finish: float = 0.0
    retainage: float = 0.0
    net_amount_due: float = 0.0

    # Status
    status: PayAppStatus = PayAppStatus.DRAFT
    submitted_date: Optional[datetime] = None
    approved_date: Optional[datetime] = None
    approved_amount: float = 0.0
    paid_date: Optional[datetime] = None
    paid_amount: float = 0.0

    # Retainage rates
    work_retainage_rate: float = 0.10
    stored_retainage_rate: float = 0.10

@dataclass
class G702Data:
    """AIA G702 Application and Certificate for Payment data."""
    application_number: int
    period_to: datetime
    project_name: str
    owner: str
    contractor: str
    architect: str

    original_contract_sum: float
    net_change_orders: float
    contract_sum_to_date: float
    total_completed_stored: float
    retainage: float
    total_earned_less_retainage: float
    less_previous_certificates: float
    current_payment_due: float
    balance_to_finish: float

class PaymentApplicationProcessor:
    """Process construction payment applications."""

    def __init__(self, project_name: str, contractor: str,
                 original_contract: float):
        self.project_name = project_name
        self.contractor = contractor
        self.original_contract = original_contract
        self.change_orders_total = 0.0

        self.schedule_of_values: List[SOVLineItem] = []
        self.pay_apps: Dict[int, PaymentApplication] = {}
        self.next_app_number = 1

        self.work_retainage_rate = 0.10
        self.stored_retainage_rate = 0.10

    def set_retainage_rates(self, work_rate: float, stored_rate: float = None):
        """Set retainage rates."""
        self.work_retainage_rate = work_rate
        self.stored_retainage_rate = stored_rate if stored_rate else work_rate

    def add_sov_item(self, number: str, description: str,
                    scheduled_value: float) -> SOVLineItem:
        """Add line item to schedule of values."""
        item = SOVLineItem(
            number=number,
            description=description,
            scheduled_value=scheduled_value
        )
        self.schedule_of_values.append(item)
        return item

    def import_sov(self, items: List[Dict]) -> int:
        """Import schedule of values from list."""
        count = 0
        for item in items:
            self.add_sov_item(
                item['number'],
                item['description'],
                item['value']
            )
            count += 1
        return count

    def add_change_order(self, amount: float, description: str = ""):
        """Add approved change order to contract."""
        self.change_orders_total += amount

        # Add as new SOV item
        co_number = f"CO-{len([i for i in self.schedule_of_values if 'CO-' in i.number])+1:03d}"
        self.add_sov_item(co_number, description or f"Change Order", amount)

    def create_pay_app(self, period_from: datetime,
                      period_to: datetime) -> PaymentApplication:
        """Create new payment application."""
        app_number = self.next_app_number

        # Copy SOV with previous values
        line_items = []
        for sov_item in self.schedule_of_values:
            # Get previous completed from last pay app
            prev_completed = 0.0
            if app_number > 1:
                prev_app = self.pay_apps.get(app_number - 1)
                if prev_app:
                    prev_item = next(
                        (i for i in prev_app.line_items if i.number == sov_item.number),
                        None
                    )
                    if prev_item:
                        prev_completed = (prev_item.previous_completed +
                                        prev_item.current_completed +
                                        prev_item.materials_stored)

            line_items.append(SOVLineItem(
                number=sov_item.number,
                description=sov_item.description,
                scheduled_value=sov_item.scheduled_value,
                previous_completed=prev_completed
            ))

        pay_app = PaymentApplication(
            application_number=app_number,
            project_name=self.project_name,
            contractor=self.contractor,
            period_from=period_from,
            period_to=period_to,
            original_contract=self.original_contract,
            change_orders=self.change_orders_total,
            contract_sum=self.original_contract + self.change_orders_total,
            line_items=line_items,
            work_retainage_rate=self.work_retainage_rate,
            stored_retainage_rate=self.stored_retainage_rate
        )

        self.pay_apps[app_number] = pay_app
        self.next_app_number += 1

        return pay_app

    def update_line_item(self, app_number: int, line_number: str,
                        current_completed: float = None,
                        materials_stored: float = None) -> SOVLineItem:
        """Update line item progress."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]
        item = next((i for i in pay_app.line_items if i.number == line_number), None)

        if not item:
            raise ValueError(f"Line item {line_number} not found")

        if current_completed is not None:
            item.current_completed = current_completed
        if materials_stored is not None:
            item.materials_stored = materials_stored

        item.calculate(pay_app.work_retainage_rate)

        # Recalculate pay app totals
        self._calculate_totals(pay_app)

        return item

    def update_by_percentage(self, app_number: int, line_number: str,
                            percent_complete: float) -> SOVLineItem:
        """Update line item by percentage complete."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]
        item = next((i for i in pay_app.line_items if i.number == line_number), None)

        if not item:
            raise ValueError(f"Line item {line_number} not found")

        # Calculate current completed from percentage
        total_earned = item.scheduled_value * (percent_complete / 100)
        item.current_completed = total_earned - item.previous_completed - item.materials_stored

        if item.current_completed < 0:
            item.current_completed = 0

        item.calculate(pay_app.work_retainage_rate)
        self._calculate_totals(pay_app)

        return item

    def _calculate_totals(self, pay_app: PaymentApplication):
        """Calculate pay app totals."""
        pay_app.total_scheduled = sum(i.scheduled_value for i in pay_app.line_items)
        pay_app.previous_completed = sum(i.previous_completed for i in pay_app.line_items)
        pay_app.current_completed = sum(i.current_completed for i in pay_app.line_items)
        pay_app.materials_stored = sum(i.materials_stored for i in pay_app.line_items)

        pay_app.total_completed = (
            pay_app.previous_completed +
            pay_app.current_completed +
            pay_app.materials_stored
        )

        pay_app.percent_complete = (
            pay_app.total_completed / pay_app.total_scheduled * 100
            if pay_app.total_scheduled > 0 else 0
        )

        pay_app.balance_to_finish = pay_app.contract_sum - pay_app.total_completed

        # Calculate retainage
        work_retainage = (pay_app.previous_completed + pay_app.current_completed) * pay_app.work_retainage_rate
        stored_retainage = pay_app.materials_stored * pay_app.stored_retainage_rate
        pay_app.retainage = work_retainage + stored_retainage

        # Previous certificates
        previous_certs = 0
        if pay_app.application_number > 1:
            prev_app = self.pay_apps.get(pay_app.application_number - 1)
            if prev_app:
                previous_certs = prev_app.total_completed - prev_app.retainage

        # Net amount due
        pay_app.net_amount_due = (
            pay_app.total_completed - pay_app.retainage - previous_certs
        )

    def submit_pay_app(self, app_number: int) -> PaymentApplication:
        """Submit pay app for review."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]
        pay_app.status = PayAppStatus.SUBMITTED
        pay_app.submitted_date = datetime.now()

        return pay_app

    def approve_pay_app(self, app_number: int,
                       approved_amount: float = None) -> PaymentApplication:
        """Approve pay app."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]
        pay_app.status = PayAppStatus.APPROVED
        pay_app.approved_date = datetime.now()
        pay_app.approved_amount = approved_amount if approved_amount else pay_app.net_amount_due

        return pay_app

    def record_payment(self, app_number: int, paid_amount: float,
                      paid_date: datetime = None) -> PaymentApplication:
        """Record payment received."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]
        pay_app.paid_date = paid_date or datetime.now()
        pay_app.paid_amount = paid_amount

        if paid_amount >= pay_app.approved_amount:
            pay_app.status = PayAppStatus.PAID
        else:
            pay_app.status = PayAppStatus.PARTIAL_PAID

        return pay_app

    def generate_g702(self, app_number: int, owner: str,
                     architect: str) -> G702Data:
        """Generate AIA G702 data."""
        if app_number not in self.pay_apps:
            raise ValueError(f"Pay app {app_number} not found")

        pay_app = self.pay_apps[app_number]

        # Previous certificates
        previous_certs = 0
        if app_number > 1:
            prev_app = self.pay_apps.get(app_number - 1)
            if prev_app:
                previous_certs = prev_app.total_completed - prev_app.retainage

        return G702Data(
            application_number=pay_app.application_number,
            period_to=pay_app.period_to,
            project_name=pay_app.project_name,
            owner=owner,
            contractor=pay_app.contractor,
            architect=architect,
            original_contract_sum=pay_app.original_contract,
            net_change_orders=pay_app.change_orders,
            contract_sum_to_date=pay_app.contract_sum,
            total_completed_stored=pay_app.total_completed,
            retainage=pay_app.retainage,
            total_earned_less_retainage=pay_app.total_completed - pay_app.retainage,
            less_previous_certificates=previous_certs,
            current_payment_due=pay_app.net_amount_due,
            balance_to_finish=pay_app.balance_to_finish
        )

    def generate_g703(self, app_number: int) -> str:
        """Generate AIA G703 continuation sheet."""
        if app_number not in self.pay_apps:
            return "Pay app not found"

        pay_app = self.pay_apps[app_number]

        lines = [
            "# AIA G703 - Continuation Sheet",
            "",
            f"**Application Number:** {pay_app.application_number}",
            f"**Period To:** {pay_app.period_to.strftime('%Y-%m-%d')}",
            "",
            "| Item | Description | Scheduled | Previous | This Period | Stored | Total | % | Balance | Retainage |",
            "|------|-------------|-----------|----------|-------------|--------|-------|---|---------|-----------|"
        ]

        for item in pay_app.line_items:
            lines.append(
                f"| {item.number} | {item.description[:20]} | "
                f"${item.scheduled_value:,.0f} | ${item.previous_completed:,.0f} | "
                f"${item.current_completed:,.0f} | ${item.materials_stored:,.0f} | "
                f"${item.previous_completed + item.current_completed + item.materials_stored:,.0f} | "
                f"{item.percent_complete:.0f}% | ${item.balance_to_finish:,.0f} | "
                f"${item.retainage:,.0f} |"
            )

        lines.extend([
            "",
            f"| **TOTALS** | | ${pay_app.total_scheduled:,.0f} | "
            f"${pay_app.previous_completed:,.0f} | ${pay_app.current_completed:,.0f} | "
            f"${pay_app.materials_stored:,.0f} | ${pay_app.total_completed:,.0f} | "
            f"{pay_app.percent_complete:.0f}% | ${pay_app.balance_to_finish:,.0f} | "
            f"${pay_app.retainage:,.0f} |"
        ])

        return "\n".join(lines)

    def get_billing_summary(self) -> Dict:
        """Get billing summary across all pay apps."""
        total_billed = sum(pa.total_completed for pa in self.pay_apps.values())
        total_paid = sum(pa.paid_amount for pa in self.pay_apps.values())
        total_retainage = sum(pa.retainage for pa in self.pay_apps.values())

        pending = [pa for pa in self.pay_apps.values()
                   if pa.status in [PayAppStatus.SUBMITTED, PayAppStatus.UNDER_REVIEW, PayAppStatus.APPROVED]]

        return {
            "contract_sum": self.original_contract + self.change_orders_total,
            "total_billed": total_billed,
            "total_paid": total_paid,
            "total_retainage": total_retainage,
            "outstanding": total_billed - total_paid - total_retainage,
            "pending_apps": len(pending),
            "pending_amount": sum(pa.net_amount_due for pa in pending),
            "percent_billed": total_billed / (self.original_contract + self.change_orders_total) * 100
        }
```

## Quick Start

```python
from datetime import datetime

# Initialize processor
processor = PaymentApplicationProcessor(
    project_name="Office Tower",
    contractor="ABC Construction",
    original_contract=5000000
)

# Import schedule of values
processor.import_sov([
    {"number": "01", "description": "General Conditions", "value": 250000},
    {"number": "02", "description": "Sitework", "value": 300000},
    {"number": "03", "description": "Concrete", "value": 800000},
    {"number": "04", "description": "Structural Steel", "value": 1200000},
    {"number": "05", "description": "MEP", "value": 1500000},
    {"number": "06", "description": "Finishes", "value": 950000},
])

# Create pay application
pay_app = processor.create_pay_app(
    period_from=datetime(2024, 1, 1),
    period_to=datetime(2024, 1, 31)
)

# Update progress
processor.update_by_percentage(pay_app.application_number, "01", 100)  # GC 100%
processor.update_by_percentage(pay_app.application_number, "02", 75)   # Site 75%
processor.update_by_percentage(pay_app.application_number, "03", 50)   # Concrete 50%
processor.update_line_item(pay_app.application_number, "04",
                          current_completed=200000, materials_stored=300000)

# Submit and approve
processor.submit_pay_app(pay_app.application_number)
processor.approve_pay_app(pay_app.application_number)

# Generate G703
print(processor.generate_g703(pay_app.application_number))

# Get summary
summary = processor.get_billing_summary()
print(f"Percent Billed: {summary['percent_billed']:.1f}%")
```

## Requirements

```bash
pip install (no external dependencies)
```

© datadrivenconstruction · MIT · datadrivenconstruction/DDC_Skills_for_AI_Agents_in_Construction

Similar skills

All skills for Finance and business →
payment-gateway-integration aj-geddes payment-gateway-integration — a Claude Code skill that wires Stripe, PayPal and Square into backends: payments, subscriptions, webhooks, refunds. Also works in Codex, Cursor, Copilot, Gemini CLI and OpenCode. CX Codex +1 531installs ATXP — Agent Payment & Wallet Infrastructure atxp-dev The ATXP — Agent Payment & Wallet Infrastructure MCP server for Claude Code equips AI agents with an Ethereum wallet and pay-as-you-go access to external APIs without managing vendor keys. CX Codex +1 ★ 46repo stars create-payment-credential stripe create-payment-credential — a Claude Code skill that pulls payment credentials from a Link wallet and finishes the checkout. Also runs on Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. CX Codex +1 27,200installs qianwen-payment QianWen-AI qianwen-payment is a skill for checking Qwen AI Platform balances, making Alipay recharges, and buying Token Plans. It also handles explicit errors for insufficient funds or overdue accounts. CX Codex +1 3,200installs payment-testing kindlmann payment-testing — a testing skill for end-to-end payment flows against Stripe, Adyen, and PayPal sandboxes. Helps automate card declines, 3DS challenges, and webhook verification. CX Codex +1 1,300installs payment-provider-protocol vtex Assists with building and debugging VTEX Payment Provider Protocol connectors. Enforces endpoint routing, payload schemas, and response rules for homologation. CX Codex +1 1,100installs

From the same set156

The whole set →
schedule-cost-link schedule-cost-link links construction schedule activities to budget line items, builds cash flow curves, and calculates earned value metrics. CX Codex +1 117installs payment-application-generator payment-application-generator generates AIA-style payment applications: tracks schedule of values, calculates retention, and produces payment documentation. CX Codex +1 117installs erp-integration-analysis The erp-integration-analysis skill maps data flows between ERP modules in construction organizations, then flags bottlenecks and suggests changes. Use it to review how systems connect. CX Codex +1 117installs etl-pipeline etl-pipeline is a skill for building construction-data workflows that extract, clean, validate, aggregate, and send results to files, databases, APIs, or dashboards. CX Codex +1 117installs dgn-to-excel dgn-to-excel converts MicroStation DGN files (v7 and v8) into structured Excel spreadsheets. Extracts CAD elements, levels, and text properties in infrastructure projects. CX Codex +1 117installs security-review-construction security-review-construction — a checklist-based skill for reviewing security in construction software, from APIs and integrations to project dashboards. Use it when handling financial, BIM/CAD, or subcontractor data. CX Codex +1 117installs toolbox-talk-generator toolbox-talk-generator creates safety briefings for construction crews using daily work, weather, incident, and seasonal details. It can prepare versions in multiple languages. CX Codex +1 117installs cwicr-bid-analyzer cwicr-bid-analyzer compares contractor pricing against CWICR benchmarks to spot cost anomalies. Helps evaluate bids and flag unbalanced line items. CX Codex +1 117installs

Project sponsors

Companies that keep this analytics open