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:
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-viewpayment 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.
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 confirmationstate.
- Ingests bank transfer receipts (such as Mexican SPEI transfers) using either Gemini vision (
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_invoicetool with payment methodBANK_TRANSFER, registering the external payment directly on the PayPal invoice. - Queries PayPal via
get_invoiceto retrieve the updated remaining balance (viadue_amountor total minuspaid_amount) and updates the unified ledger state topartially paidorpaid. - 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=SANDBOXrequired). - 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 withsend_to_recipient: falseto retrieve directpayer-viewlinks 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.
- Integrated via
- AI Tooling & Agent Architecture:
- Built with the Vercel AI SDK (
aiv7.0.162) and Google AI SDK (@ai-sdk/googlev4.0.111). - Vision Extraction: Structured receipt extraction with
generateObjectand Google Gemini vision models (LectorComprobanteReal), validated via Zod schemas. - Contextual Copywriting: Generative debt collection messaging (
RedactorGeminiwithgemini-3.5-flashby default, configurable viaOKI_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.
- Built with the Vercel AI SDK (
- Configurable Regional Payment Rails:
config/transferencias.jsonprovides a modular schema for transfer rails, supporting Mexican SPEI (with reference, tracking codeclaveRastreo, and issuing bankbancoEmisor) 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
- PayPal Sandbox API Nuances:
send_invoicereturns 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 settingsend_to_recipient: falseand extracting the direct HATEOASpayer-viewURL from the response.generate_invoice_qr_codereturns 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.
- Reconciling Partial Payments Accurately:
- Depending on invoice lifecycle states, PayPal's API may return
due_amountor require computing the balance from totalamountminuspayments.paid_amount. We implemented resilient balance resolution inPayPalReal.consultarto ensure the local ledger always mirrors PayPal's exact balance to the cent.
- Depending on invoice lifecycle states, PayPal's API may return
- 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, andrecord_payment_for_invoice), Vercel AI SDK (aiv7.0.162), Google Gemini vision (@ai-sdk/googlev4.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
paypalpaypal-agent-toolkitpaypal-sandboxtypescriptnode.jsvercel-ai-sdkgoogle-geminizodvitest
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
- node.js
- paypal
- paypal-agent-toolkit
- paypal-sandbox
- typescript
- vercel-ai-sdk
- vitest
- zod