Twill Brain

Design a rate recommendation system (vs. potential commission)

2 min read

Design a rate recommendation system (vs. potential commission)

Repo: · Issue: #572 Status: Open · Priority: P2 Assignee: Ahmad1809

Description

Overview

Design and implement a rate recommendation system that analyzes merchant processing statements and recommends optimal pricing — showing potential savings for the merchant and potential commission for the ISO/agent.

This builds on top of the existing statement analysis pipeline (n8n + PricingStep UI) and connects to the commission estimation logic Ahmad built in facade (#471).

Current State — What Already Exists

1. Fee Inspector (feeinspector.com)

Public-facing statement analysis tool. A merchant or agent uploads a processor statement PDF and gets:

  • Current effective rate breakdown (all-in %)
  • Fee decomposition (processor markup, PCI, batch, auth, other)
  • Card type mix (credit/debit/Amex percentages)
  • Partner rate comparisons (Custom Rate, Flat Rate, Interchange Plus)
  • Monthly savings estimate vs partner network

The UI shows a “Recommended” partner plan with savings like $24/mo (25% off) and a visual fee comparison bar chart (interchange → assessments → current markup → partner markup → fixed fees).

2. n8n Statement Parsing Workflow

Backend pipeline that powers both Fee Inspector and the in-app PricingStep. Triggered via webhook (POST /webhook/f7b50221-0b54-4d5b-83ca-83bcb51588fb, basic auth).

Flow:

  1. PDF upload → text extraction → image-based detection (if <50 chars of text per page)
  2. Image-based path: PDF → JPG (ConvertAPI) → GPT-4o vision → structured extraction (Azure gpt-4.1)
  3. Text-based path: text preprocessing (section extraction, monetary value detection, table parsing) → AI Agent (twill-mini on Azure) with structured output parser
  4. Both paths output the same schema:
totalTransactionVolume    { total, amex, visaMasterDiscover }
totalFees                 { total, amex, visaMasterDiscover }
totalAuthorizationFees    { total, amex, visaMasterDiscover }
numberOfAuthorizations    { total, amex, visaMasterDiscover }
discountCharges           { total, amex, visaMasterDiscover }
otherFees        

## Implementation Notes
_Dash adds notes here while working_

## Related
_Link to people, meetings, dependent tickets_

Graph View