OKI by AsisT — Autonomous Accounts Receivable & Reconciliation Agent for Small Businesses


Inspiration

In Mexico, small service businesses (such as medical practices, repair shops, private schools, and consulting firms) rarely get paid through a single channel. Customers pay some bills by card, send bank-transfer (SPEI) payment screenshots over WhatsApp or chat, or pay the remainder in cash. As a result, business owners spend hours manually chasing overdue payments and spending late evenings matching chat screenshots against bank accounts and notebooks. Furthermore, directly asking clients for money is awkward, friction-heavy, and easy to postpone.

PayPal provides the ideal solution for card acceptance without requiring physical POS terminals or forcing customers to hold a PayPal account (customers can pay PayPal invoices directly by card as guests). However, until now, external payments like local bank transfers remained completely disconnected from PayPal.

We created OKI to bridge this gap: an autonomous accounts receivable agent that acts on the owner's behalf within strict business rules. OKI automates payment collection via PayPal, reads transfer receipts using AI vision, enforces deterministic fraud guardrails, and records approved off-platform transfers directly into PayPal using record_payment_for_invoice. PayPal becomes the single source of truth and unified ledger for every payment channel.


What it does

OKI executes an end-to-end accounts receivable and reconciliation workflow for small service businesses:

  1. Autonomous Invoice Creation & Payment Dispatch:

    • Scans the business ledger for overdue accounts designated for PayPal.
    • Generates official PayPal invoices configured with the owner's partial payment policy (e.g., minimum 30% partial payment allowed).
    • Generates both direct payer-view payment URLs and scannable QR codes.
    • Drafts polite, contextual payment notifications in English or Spanish (via deterministic templates in the keyless CLI or adapting to the merchant's chosen casual/formal tone via RedactorGemini), delivering the direct link to the customer.
  2. AI Receipt Reading & Multi-Channel Reconciliation:

    • Ingests bank transfer receipts (such as Mexican SPEI transfers) using either Gemini vision (LectorComprobanteReal) or fixture validation for the keyless demo (LectorComprobanteSimulado) to extract structured metadata matching a strict Zod schema: amount (monto), currency (moneda: MXN), date (fecha), transfer method (metodo), reference number (referencia), optional bank (banco), and model confidence score (confianza).
    • Evaluates extracted receipts against six deterministic business rules before touching any financial record: verifying confidence thresholds, detecting duplicate references, validating date windows (within 7 days), checking amounts against account balances, and ensuring unique candidate matching.
    • When matching succeeds, the receipt is placed in an awaiting confirmation state.
  3. Gated Execution & Single Unified Ledger in PayPal:

    • Enforces a strict human-in-the-loop gate: no transaction is recorded in PayPal without the owner's explicit one-tap approval.
    • Upon owner approval, OKI calls PayPal's record_payment_for_invoice tool with payment method BANK_TRANSFER, registering the external payment directly on the PayPal invoice.
    • Queries PayPal via get_invoice to retrieve the updated remaining balance (via due_amount or total minus paid_amount) and updates the unified ledger state to partially paid or paid.
    • Flags suspicious receipts (e.g., duplicate reference numbers or mismatched amounts) immediately as suspicious, blocking automated recording and requiring dedicated owner audit (aprobarRevisado).

How we built it

OKI is built on Node.js and TypeScript, designed specifically for the PayPal Developer Platform and modern AI agent tooling:

  • PayPal Developer Platform & Agent Toolkit:
    • Integrated via @paypal/agent-toolkit/ai-sdk (v1.11.0) with strict sandbox gating (PAYPAL_ENVIRONMENT=SANDBOX required).
    • Orchestrates five core PayPal tools:
    • create_invoice: Invoicing with itemized amounts, MXN currency, and partial payment allowances (allow_partial_payment, minimum_partial_payment_amount).
    • send_invoice: Configured with send_to_recipient: false to retrieve direct payer-view links without requiring customer emails.
    • generate_invoice_qr_code: Generates scannable invoice QR codes, parsed from multipart responses into base64 PNG data URLs.
    • get_invoice: Fetches live invoice details, invoice status, and dynamic balance (due_amount).
    • record_payment_for_invoice: Registers external bank transfers (BANK_TRANSFER) to reconcile off-platform payments on the PayPal platform.
  • AI Tooling & Agent Architecture:
    • Built with the Vercel AI SDK (ai v7.0.162) and Google AI SDK (@ai-sdk/google v4.0.111).
    • Vision Extraction: Structured receipt extraction with generateObject and Google Gemini vision models (LectorComprobanteReal), validated via Zod schemas.
    • Contextual Copywriting: Generative debt collection messaging (RedactorGemini with gemini-3.5-flash by default, configurable via OKI_GEMINI_MODEL) adapting tone and language while preserving demo markers and payment URLs.
    • Deterministic Guardrails: AI handles perception and text drafting, but never executes monetary mutations. Matching logic, fraud checks, and policy thresholds are 100% deterministic TypeScript functions validated with Zod.
  • Configurable Regional Payment Rails:
    • config/transferencias.json provides a modular schema for transfer rails, supporting Mexican SPEI (with reference, tracking code claveRastreo, and issuing bank bancoEmisor) and generic transfers.
  • Reliability & Testing:
    • Comprehensive test suite in Vitest (28 passing tests and 2 intentional mutation tests verifying policy rejection).
    • Clean TypeScript build (tsc --noEmit).

Challenges we ran into

  1. PayPal Sandbox API Nuances:
    • send_invoice returns an HTTP 422 error ("Missing recipient email") if the customer record lacks an email address. Since small business debtors are frequently reached via messaging apps rather than email, we resolved this by setting send_to_recipient: false and extracting the direct HATEOAS payer-view URL from the response.
    • generate_invoice_qr_code returns a raw HTTP multipart body containing binary PNG image data rather than a plain JSON object. We engineered a custom multipart boundary extractor (pngDesdeMultipart) that verifies PNG magic header bytes and safely converts the image into a standard data URL.
  2. Reconciling Partial Payments Accurately:
    • Depending on invoice lifecycle states, PayPal's API may return due_amount or require computing the balance from total amount minus payments.paid_amount. We implemented resilient balance resolution in PayPalReal.consultar to ensure the local ledger always mirrors PayPal's exact balance to the cent.
  3. Eliminating AI Hallucinations in Financial State:
    • Financial operations cannot tolerate probabilistic errors or hallucinated numbers. We designed an explicit firewall between the AI receipt reader and the PayPal execution adapter: receipts are parsed into strongly typed Zod objects, evaluated against six deterministic fraud rules, and held in an uncommitted state until the business owner explicitly taps to approve.

Accomplishments that we're proud of

  • Live Sandbox End-to-End Verification: Executed live against the PayPal Developer Platform Sandbox, successfully creating invoices, dispatching payment links, recording a 40% external bank transfer, and querying the updated balance ($720.00 MXN remaining on a $1200.00 MXN invoice).
  • 100% Zero-Key Demo: Created a completely self-contained, keyless CLI demo (npm run demo / npm run demo:es) that allows any hackathon judge to clone the repository and evaluate the complete lifecycle in seconds without configuring API keys.
  • Full Bilingual Native Support: Built true bilingual capabilities from the ground up: the CLI, account summaries, debtor messages, and Gemini prompts switch cleanly between English and Spanish via OKI_LANG=es.
  • Rigorous Verification & Test Coverage: Achieved 28 passing unit and integration tests in Vitest, including test coverage for real recorded PayPal responses, HATEOAS link resolution, multipart QR parsing, and intentional mutation controls.

Alignment with Hackathon Judging Criteria

OKI was architected to directly address the five official judging criteria from devpost-rules.txt:196-206:

  • Technological Implementation: Built on Node.js and TypeScript, deeply integrating @paypal/agent-toolkit/ai-sdk (v1.11.0) with five distinct PayPal tools (create_invoice, send_invoice, generate_invoice_qr_code, get_invoice, and record_payment_for_invoice), Vercel AI SDK (ai v7.0.162), Google Gemini vision (@ai-sdk/google v4.0.111), and 28 passing automated tests in Vitest.
  • Design: Complete and coherent product experience featuring a 6-account multi-rail ledger, strict human-in-the-loop approval gate before modifying any financial state, clean dual-mode CLI and JSON output, and native end-to-end bilingual support (en / es).
  • Potential Impact: Solves the high-friction, multi-channel payment chaos for Mexican small service businesses by providing guest-checkout card acceptance without physical terminals, recovering cash flow, and maintaining exact balance accuracy.
  • Innovation/Idea: Bridges off-platform bank transfers (SPEI) into PayPal as a single source of truth via record_payment_for_invoice, protected by an innovative 6-rule deterministic fraud verification firewall before any ledger mutation.
  • Presentation: Clear, zero-dependency reproducible evaluation for judges (npm run demo / npm run demo:es), complete sandbox reproducibility with developer credentials, video demonstration, and sanitized security practices with zero credentials in code.

What we learned

  • Real-world fintech agent architecture demands robust defensive engineering: handling raw multipart payloads, HATEOAS relations, and API edge cases is just as critical as prompt design.
  • The most effective AI agent design pattern for business operations is a hybrid one: leverage AI for multi-modal perception and contextual communication, but strictly delegate business rules, fraud detection, and transactional execution to deterministic code with human-in-the-loop checkpoints.

What's next for OKI

To maintain absolute transparency with the judges, we clearly distinguish what is built and working today (autonomous invoice creation, QR generation, deterministic fraud matching, owner one-tap approval, and PayPal external payment recording — all exercised in the keyless and sandbox demos; the Gemini receipt reader and Gemini message writer are implemented in code and require a Gemini API key, so the keyless demo uses deterministic stand-ins) from our future development roadmap:

  • Conversational Payment Negotiation (F3 Roadmap): Enabling customers to negotiate installment plans or early-payment settlement discounts in a multi-turn chat, automatically bound by the owner's pre-configured policy limits.
  • Dedicated Web Dashboard (F4 Roadmap): Replacing the current dual-format CLI output with a web interface featuring interactive ledger cards, receipt inspection sidebars, and one-tap approval buttons.
  • Direct Messaging Integrations: Deploying native WhatsApp Business API and SMS webhooks to deliver payment links and receive transfer screenshots directly within mobile chat threads.
  • Mexican Electronic Invoicing (CFDI SAT): Integrating certified fiscal pacs to automatically emit official Mexican tax invoices (CFDI) once a PayPal or SPEI payment is fully settled.
  • Direct Banking Verification (Banxico CEP): Validating SPEI tracking codes against Banco de México's electronic payment certification service for automated interbank clearance confirmation.

Built with

  • paypal
  • paypal-agent-toolkit
  • paypal-sandbox
  • typescript
  • node.js
  • vercel-ai-sdk
  • google-gemini
  • zod
  • vitest

Try it out (Testing instructions)

Judges can test OKI immediately. No paid accounts or API keys are required to test the complete application.

Prerequisites

  • Node.js v20 or higher installed.
  • Git.

Step 1: Clone and install

git clone https://github.com/GabrielMarquez01/oki-by-asist.git
cd oki-by-asist
npm install

Step 2: Run automated tests

Verify the 28 passing tests and 2 mutation control checks:

npm test

Step 3: Run the keyless demo (English default)

Runs the end-to-end accounts receivable workflow: shows the initial account summary, creates PayPal invoices, processes a valid SPEI receipt, records owner approval, flags a suspicious duplicate receipt, dispatches debtor messages, and prints the updated ledger:

npm run demo

Step 4: Run the keyless demo in Spanish

Runs the exact same workflow fully localized in Spanish:

npm run demo:es

Step 5: (Optional) Run against live PayPal Sandbox with your own credentials

To test OKI with live calls against the PayPal Developer Platform Sandbox, provide your own test credentials from developer.paypal.com (no keys are stored in this repository):

export PAYPAL_CLIENT_ID="your-sandbox-client-id"
export PAYPAL_CLIENT_SECRET="your-sandbox-client-secret"
export PAYPAL_ENVIRONMENT="SANDBOX"

# Run live sandbox in English
npm run demo:sandbox

# Run live sandbox in Spanish
npm run demo:sandbox:es
# (or: OKI_LANG=es npm run demo:sandbox)

Built With

Share this project:

Updates

Submission history