Invoice Duplicate Recovery

Computes exact overpayments across caller-supplied approved invoices, payments, and recorded credits, and produces an evidence bundle for requesting vendor credit review. Never sends requests, never asserts legal refund entitlement, and never takes automatic financial action.

Pricing

0.05 per analysis

Requires x402 capable MCP client with wallet for payment settlement.

Input Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "invoices",
    "payments"
  ],
  "anyOf": [
    {
      "required": [
        "invoices"
      ],
      "properties": {
        "invoices": {
          "minItems": 1
        }
      }
    },
    {
      "required": [
        "payments"
      ],
      "properties": {
        "payments": {
          "minItems": 1
        }
      }
    },
    {
      "required": [
        "credits"
      ],
      "properties": {
        "credits": {
          "minItems": 1
        }
      }
    }
  ],
  "properties": {
    "invoices": {
      "type": "array",
      "maxItems": 500,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "vendor_id",
          "invoice_id",
          "currency",
          "minor_unit_digits",
          "amount"
        ],
        "properties": {
          "vendor_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "invoice_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "minor_unit_digits": {
            "type": "integer",
            "minimum": 0,
            "maximum": 6
          },
          "amount": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d{0,14})(\\.\\d{1,6})?$",
            "description": "Canonical non-negative decimal string, exact, no rounding."
          }
        }
      }
    },
    "payments": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "payment_id",
          "vendor_id",
          "invoice_id",
          "currency",
          "amount"
        ],
        "properties": {
          "payment_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "vendor_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "invoice_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "amount": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d{0,14})(\\.\\d{1,6})?$"
          }
        }
      }
    },
    "credits": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "credit_id",
          "payment_id",
          "amount"
        ],
        "properties": {
          "credit_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "payment_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "amount": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d{0,14})(\\.\\d{1,6})?$"
          }
        }
      }
    }
  }
}

Example Input

{
  "invoices": [
    {
      "vendor_id": "V1",
      "invoice_id": "INV-100",
      "currency": "USD",
      "minor_unit_digits": 2,
      "amount": "100.00"
    }
  ],
  "payments": [
    {
      "payment_id": "P1",
      "vendor_id": "V1",
      "invoice_id": "INV-100",
      "currency": "USD",
      "amount": "100.00"
    },
    {
      "payment_id": "P2",
      "vendor_id": "V1",
      "invoice_id": "INV-100",
      "currency": "USD",
      "amount": "100.00"
    }
  ],
  "credits": [
    {
      "credit_id": "C1",
      "payment_id": "P2",
      "amount": "20.00"
    }
  ]
}

Example Output

{
  "ok": true,
  "disclaimer": "Computed evidence bundle for requesting vendor credit review. Not a legal or financial determination of refund entitlement, and no request or financial action is sent or taken automatically.",
  "counts": {
    "invoices": 1,
    "payments": 2,
    "credits": 1,
    "credit_requests": 1,
    "issues": 0,
    "duplicate_imports": 0
  },
  "invoices": [
    {
      "vendor_id": "V1",
      "invoice_id": "INV-100",
      "currency": "USD",
      "minor_unit_digits": 2,
      "issues": [],
      "summary": {
        "expected_minor": "10000",
        "expected": "100.00",
        "gross_minor": "20000",
        "gross": "200.00",
        "credited_minor": "2000",
        "credited": "20.00",
        "net_minor": "18000",
        "net": "180.00",
        "overpaid_minor": "8000",
        "overpaid": "80.00",
        "outstanding_minor": "0",
        "outstanding": "0.00"
      },
      "payment_ids": [
        "P1",
        "P2"
      ],
      "credit_ids": [
        "C1"
      ],
      "excluded_payment_ids": []
    }
  ],
  "orphan_payments": [],
  "orphan_credits": [],
  "duplicate_imports": [],
  "credit_requests": [
    {
      "vendor_id": "V1",
      "invoice_id": "INV-100",
      "currency": "USD",
      "amount_minor": "8000",
      "amount": "80.00",
      "reason": "net_payments_exceed_supplied_invoice_total",
      "payment_ids": [
        "P1",
        "P2"
      ],
      "credit_ids": [
        "C1"
      ],
      "evidence": {
        "invoice": {
          "vendor_id": "V1",
          "invoice_id": "INV-100",
          "currency": "USD",
          "amount": "100.00"
        },
        "payments": [
          {
            "payment_id": "P1",
            "amount": "100.00",
            "currency": "USD"
          },
          {
            "payment_id": "P2",
            "amount": "100.00",
            "currency": "USD"
          }
        ],
        "credits": [
          {
            "credit_id": "C1",
            "payment_id": "P2",
            "amount": "20.00"
          }
        ]
      }
    }
  ]
}

Limitations

• Structural validation only: unknown fields, wrong types, malformed IDs/currency/amount strings, or out-of-range minor_unit_digits are refused outright (admission fails) rather than reported as issues.
• Business-data problems (duplicate/conflicting invoice keys, duplicate or conflicting payment/credit IDs, missing invoice/payment links, currency mismatch between a payment and its invoice, amount precision exceeding the invoice minor_unit_digits, credits exceeding their linked payment) are reported as issues on the affected invoice, never silently guessed or repaired.
• Any issue touching an invoice suppresses that invoice summary and credit_request, even if a trustworthy subset would otherwise show an overpayment, so the evidence bundle never publishes a seemingly complete partial total.
• Exact duplicate records (identical full record sharing a payment_id, credit_id, or invoice vendor_id+invoice_id key) are recognized as repeated imports and counted once; distinct payment_ids against the same invoice are treated as separate real installments, not duplicates.
• All arithmetic is exact BigInt minor-unit math derived from canonical decimal strings; there is no rounding anywhere, and no floating point is used, so amounts far beyond Number.MAX_SAFE_INTEGER are handled exactly.
• No currency conversion is performed. A payment must share its invoice currency exactly to be included in that invoice totals.
• This tool never sends any request, never contacts the vendor, never asserts legal refund entitlement, and never performs any automatic financial action. Output is evidence for the caller to use at their own discretion.
• Bounded input only: payload <= 128 KiB, structural depth <= 10, <= 20000 total nodes, <= 500 invoices, <= 1000 payments, <= 1000 credits.
• Results at most 96 KiB; retry identical input and authorization within 24 hours to recover a purchase.

Connect via MCP

Add to your MCP client configuration:

{
  "mcpServers": {
    "invoice-duplicate-recovery": {
      "type": "http",
      "url": "https://mcp-factory.bowling-anthony.workers.dev/invoice-duplicate-recovery/mcp"
    }
  }
}